From 553852806dfea7b9d8fb03a1ca4f51d8e31b3a3c Mon Sep 17 00:00:00 2001 From: Michael Howell Date: Sat, 20 Feb 2021 14:43:25 -0700 Subject: [PATCH 1/8] Use the first paragraph, instead of cookie-cutter text, for rustdoc descriptions Fixes #82283 --- src/librustdoc/html/render/mod.rs | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs index f5eb92c1bb5aa..d7d69bc29f81e 100644 --- a/src/librustdoc/html/render/mod.rs +++ b/src/librustdoc/html/render/mod.rs @@ -534,12 +534,17 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> { if !root_path.ends_with('/') { root_path.push('/'); } + let description = krate + .module + .as_ref() + .and_then(|item| Some(plain_text_summary(item.doc_value()?.as_str()))) + .unwrap_or_else(|| String::from("List of all items in this crate")); let mut page = layout::Page { title: "List of all items in this crate", css_class: "mod", root_path: "../", static_root_path: self.shared.static_root_path.as_deref(), - description: "List of all items in this crate", + description: description.as_str(), keywords: BASIC_KEYWORDS, resource_suffix: &self.shared.resource_suffix, extra_scripts: &[], @@ -1548,7 +1553,10 @@ impl Context<'_> { } title.push_str(" - Rust"); let tyname = it.type_(); - let desc = if it.is_crate() { + let desc = it.doc_value().as_ref().map(|doc| plain_text_summary(&doc)); + let desc = if let Some(desc) = desc { + desc + } else if it.is_crate() { format!("API documentation for the Rust `{}` crate.", self.shared.layout.krate) } else { format!( From 1bedd4d6781aaf5e45d19b1f85db6cc28bfd2f4e Mon Sep 17 00:00:00 2001 From: Michael Howell Date: Sat, 20 Feb 2021 16:45:56 -0700 Subject: [PATCH 2/8] Cut off plain text descriptions after headers Before: The Rust Standard LibraryThe Rust Standard Library is the foundation of portable Rust software, a set of minimal and battle-tested shared abstractions for the broader Rust ecosystem. It offers core types, like `Vec` and `Option`, library-defined operations on language primitives, standard macros, I/O and multithreading, among many other things. After: The Rust Standard Library --- src/librustdoc/html/markdown.rs | 1 + src/librustdoc/html/markdown/tests.rs | 1 + 2 files changed, 2 insertions(+) diff --git a/src/librustdoc/html/markdown.rs b/src/librustdoc/html/markdown.rs index a81fd55f6f192..b7854bbf82b17 100644 --- a/src/librustdoc/html/markdown.rs +++ b/src/librustdoc/html/markdown.rs @@ -1124,6 +1124,7 @@ crate fn plain_text_summary(md: &str) -> String { Event::HardBreak | Event::SoftBreak => s.push(' '), Event::Start(Tag::CodeBlock(..)) => break, Event::End(Tag::Paragraph) => break, + Event::End(Tag::Heading(..)) => break, _ => (), } } diff --git a/src/librustdoc/html/markdown/tests.rs b/src/librustdoc/html/markdown/tests.rs index 9da3072ec282f..994fe8206e8d4 100644 --- a/src/librustdoc/html/markdown/tests.rs +++ b/src/librustdoc/html/markdown/tests.rs @@ -230,6 +230,7 @@ fn test_plain_text_summary() { t("code `let x = i32;` ...", "code `let x = i32;` ..."); t("type `Type<'static>` ...", "type `Type<'static>` ..."); t("# top header", "top header"); + t("# top header\n\nfollowed by some text", "top header"); t("## header", "header"); t("first paragraph\n\nsecond paragraph", "first paragraph"); t("```\nfn main() {}\n```", ""); From bcef5e70774c792b17b5092859392f131f78bd3a Mon Sep 17 00:00:00 2001 From: Michael Howell Date: Sat, 20 Feb 2021 17:26:05 -0700 Subject: [PATCH 3/8] Revert changes to all.html This code wasn't actually working, and trying to SEO optimize that page is pointless anyway. --- src/librustdoc/html/render/mod.rs | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs index d7d69bc29f81e..87b5ae49d7fbc 100644 --- a/src/librustdoc/html/render/mod.rs +++ b/src/librustdoc/html/render/mod.rs @@ -534,17 +534,12 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> { if !root_path.ends_with('/') { root_path.push('/'); } - let description = krate - .module - .as_ref() - .and_then(|item| Some(plain_text_summary(item.doc_value()?.as_str()))) - .unwrap_or_else(|| String::from("List of all items in this crate")); let mut page = layout::Page { title: "List of all items in this crate", css_class: "mod", root_path: "../", static_root_path: self.shared.static_root_path.as_deref(), - description: description.as_str(), + description: "List of all items in this crate", keywords: BASIC_KEYWORDS, resource_suffix: &self.shared.resource_suffix, extra_scripts: &[], From 8b3b1c922e323a9598e1225c67a7fbc81276cb1e Mon Sep 17 00:00:00 2001 From: Michael Howell Date: Sat, 20 Feb 2021 17:38:41 -0700 Subject: [PATCH 4/8] Add rustdoc UI tests for new description behaviour --- src/test/rustdoc/description.rs | 19 +++++++++++++++++++ src/test/rustdoc/description_default.rs | 12 ++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 src/test/rustdoc/description.rs create mode 100644 src/test/rustdoc/description_default.rs diff --git a/src/test/rustdoc/description.rs b/src/test/rustdoc/description.rs new file mode 100644 index 0000000000000..869950a844aab --- /dev/null +++ b/src/test/rustdoc/description.rs @@ -0,0 +1,19 @@ +#![crate_name = "foo"] +//! # Description test crate +//! +//! This is the contents of the test crate docstring. It should not show up in the description. + +// @matches 'foo/index.html' '//meta[@name="description"]/@content' 'Description test crate' + +// @matches 'foo/foo_mod/index.html' '//meta[@name="description"]/@content' 'First paragraph description.' +/// First paragraph description. +/// +/// Second paragraph should not show up. +pub mod foo_mod { + pub struct __Thing {} +} + +// @matches 'foo/fn.foo_fn.html' '//meta[@name="description"]/@content' 'Only paragraph.' +/// Only paragraph. +pub fn foo_fn() {} + diff --git a/src/test/rustdoc/description_default.rs b/src/test/rustdoc/description_default.rs new file mode 100644 index 0000000000000..e36f2be00e48f --- /dev/null +++ b/src/test/rustdoc/description_default.rs @@ -0,0 +1,12 @@ +#![crate_name = "foo"] + +// @matches 'foo/index.html' '//meta[@name="description"]/@content' 'API documentation for the Rust `foo` crate.' + +// @matches 'foo/foo_mod/index.html' '//meta[@name="description"]/@content' 'API documentation for the Rust `foo_mod` mod in crate `foo`.' +pub mod foo_mod { + pub struct __Thing {} +} + +// @matches 'foo/fn.foo_fn.html' '//meta[@name="description"]/@content' 'API documentation for the Rust `foo_fn` fn in crate `foo`.' +pub fn foo_fn() {} + From dcf49916e4fac986b602f345b60b712cd536494d Mon Sep 17 00:00:00 2001 From: Michael Howell Date: Sat, 20 Feb 2021 17:50:01 -0700 Subject: [PATCH 5/8] Fix formatting for description rustdoc UI tests --- src/test/rustdoc/description.rs | 13 ++++++++----- src/test/rustdoc/description_default.rs | 10 ++++++---- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/src/test/rustdoc/description.rs b/src/test/rustdoc/description.rs index 869950a844aab..45aff9a29f919 100644 --- a/src/test/rustdoc/description.rs +++ b/src/test/rustdoc/description.rs @@ -1,11 +1,14 @@ #![crate_name = "foo"] //! # Description test crate //! -//! This is the contents of the test crate docstring. It should not show up in the description. +//! This is the contents of the test crate docstring. +//! It should not show up in the description. -// @matches 'foo/index.html' '//meta[@name="description"]/@content' 'Description test crate' +// @matches 'foo/index.html' '//meta[@name="description"]/@content' \ +// 'Description test crate' -// @matches 'foo/foo_mod/index.html' '//meta[@name="description"]/@content' 'First paragraph description.' +// @matches 'foo/foo_mod/index.html' '//meta[@name="description"]/@content' \ +// 'First paragraph description.' /// First paragraph description. /// /// Second paragraph should not show up. @@ -13,7 +16,7 @@ pub mod foo_mod { pub struct __Thing {} } -// @matches 'foo/fn.foo_fn.html' '//meta[@name="description"]/@content' 'Only paragraph.' +// @matches 'foo/fn.foo_fn.html' '//meta[@name="description"]/@content' \ +// 'Only paragraph.' /// Only paragraph. pub fn foo_fn() {} - diff --git a/src/test/rustdoc/description_default.rs b/src/test/rustdoc/description_default.rs index e36f2be00e48f..6868dd3bfd232 100644 --- a/src/test/rustdoc/description_default.rs +++ b/src/test/rustdoc/description_default.rs @@ -1,12 +1,14 @@ #![crate_name = "foo"] -// @matches 'foo/index.html' '//meta[@name="description"]/@content' 'API documentation for the Rust `foo` crate.' +// @matches 'foo/index.html' '//meta[@name="description"]/@content' \ +// 'API documentation for the Rust `foo` crate.' -// @matches 'foo/foo_mod/index.html' '//meta[@name="description"]/@content' 'API documentation for the Rust `foo_mod` mod in crate `foo`.' +// @matches 'foo/foo_mod/index.html' '//meta[@name="description"]/@content' \ +// 'API documentation for the Rust `foo_mod` mod in crate `foo`.' pub mod foo_mod { pub struct __Thing {} } -// @matches 'foo/fn.foo_fn.html' '//meta[@name="description"]/@content' 'API documentation for the Rust `foo_fn` fn in crate `foo`.' +// @matches 'foo/fn.foo_fn.html' '//meta[@name="description"]/@content' \ +// 'API documentation for the Rust `foo_fn` fn in crate `foo`.' pub fn foo_fn() {} - From fd5a710092fe1e7668c55999c12104c122da732a Mon Sep 17 00:00:00 2001 From: Michael Howell Date: Sat, 20 Feb 2021 17:51:41 -0700 Subject: [PATCH 6/8] Use has for non-regexes --- src/test/rustdoc/description.rs | 6 +++--- src/test/rustdoc/description_default.rs | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/test/rustdoc/description.rs b/src/test/rustdoc/description.rs index 45aff9a29f919..79990203c4053 100644 --- a/src/test/rustdoc/description.rs +++ b/src/test/rustdoc/description.rs @@ -4,10 +4,10 @@ //! This is the contents of the test crate docstring. //! It should not show up in the description. -// @matches 'foo/index.html' '//meta[@name="description"]/@content' \ +// @has 'foo/index.html' '//meta[@name="description"]/@content' \ // 'Description test crate' -// @matches 'foo/foo_mod/index.html' '//meta[@name="description"]/@content' \ +// @has 'foo/foo_mod/index.html' '//meta[@name="description"]/@content' \ // 'First paragraph description.' /// First paragraph description. /// @@ -16,7 +16,7 @@ pub mod foo_mod { pub struct __Thing {} } -// @matches 'foo/fn.foo_fn.html' '//meta[@name="description"]/@content' \ +// @has 'foo/fn.foo_fn.html' '//meta[@name="description"]/@content' \ // 'Only paragraph.' /// Only paragraph. pub fn foo_fn() {} diff --git a/src/test/rustdoc/description_default.rs b/src/test/rustdoc/description_default.rs index 6868dd3bfd232..21d8e04d3f95a 100644 --- a/src/test/rustdoc/description_default.rs +++ b/src/test/rustdoc/description_default.rs @@ -1,14 +1,14 @@ #![crate_name = "foo"] -// @matches 'foo/index.html' '//meta[@name="description"]/@content' \ +// @has 'foo/index.html' '//meta[@name="description"]/@content' \ // 'API documentation for the Rust `foo` crate.' -// @matches 'foo/foo_mod/index.html' '//meta[@name="description"]/@content' \ +// @has 'foo/foo_mod/index.html' '//meta[@name="description"]/@content' \ // 'API documentation for the Rust `foo_mod` mod in crate `foo`.' pub mod foo_mod { pub struct __Thing {} } -// @matches 'foo/fn.foo_fn.html' '//meta[@name="description"]/@content' \ +// @has 'foo/fn.foo_fn.html' '//meta[@name="description"]/@content' \ // 'API documentation for the Rust `foo_fn` fn in crate `foo`.' pub fn foo_fn() {} From a6b85fbc78280c8caae26769191b787ad8543ddf Mon Sep 17 00:00:00 2001 From: Michael Howell Date: Sun, 21 Feb 2021 09:31:23 -0700 Subject: [PATCH 7/8] Update src/test/rustdoc/description.rs Co-authored-by: Joshua Nelson --- src/test/rustdoc/description.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/src/test/rustdoc/description.rs b/src/test/rustdoc/description.rs index 79990203c4053..a95f177f6b0b0 100644 --- a/src/test/rustdoc/description.rs +++ b/src/test/rustdoc/description.rs @@ -9,6 +9,7 @@ // @has 'foo/foo_mod/index.html' '//meta[@name="description"]/@content' \ // 'First paragraph description.' +// @!has - '//meta[@name="description"]/@content' 'Second paragraph' /// First paragraph description. /// /// Second paragraph should not show up. From 575c75b324ee7557b776f6dce6f4f77f5f7887a1 Mon Sep 17 00:00:00 2001 From: Michael Howell Date: Sun, 21 Feb 2021 09:31:39 -0700 Subject: [PATCH 8/8] Update src/test/rustdoc/description.rs Co-authored-by: Joshua Nelson --- src/test/rustdoc/description.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/src/test/rustdoc/description.rs b/src/test/rustdoc/description.rs index a95f177f6b0b0..05ec428220847 100644 --- a/src/test/rustdoc/description.rs +++ b/src/test/rustdoc/description.rs @@ -6,6 +6,7 @@ // @has 'foo/index.html' '//meta[@name="description"]/@content' \ // 'Description test crate' +// @!has - '//meta[@name="description"]/@content' 'should not show up' // @has 'foo/foo_mod/index.html' '//meta[@name="description"]/@content' \ // 'First paragraph description.'