From e0822ecdbc43a6128136661bb73fb6f3c3db2b4a Mon Sep 17 00:00:00 2001 From: Andy Russell Date: Sat, 27 Jun 2020 16:44:42 -0400 Subject: rustdoc: do not use plain summary for trait impls Fixes #38386. Fixes #48332. Fixes #49430. Fixes #62741. Fixes #73474. --- src/librustdoc/html/render/cache.rs | 6 ++-- src/librustdoc/html/render/mod.rs | 62 ++++++++++++++++++++----------------- 2 files changed, 36 insertions(+), 32 deletions(-) (limited to 'src/librustdoc/html/render') diff --git a/src/librustdoc/html/render/cache.rs b/src/librustdoc/html/render/cache.rs index ccc07645620..cf785d362cd 100644 --- a/src/librustdoc/html/render/cache.rs +++ b/src/librustdoc/html/render/cache.rs @@ -9,7 +9,7 @@ use crate::clean::types::GetDefId; use crate::clean::{self, AttributesExt}; use crate::formats::cache::Cache; use crate::formats::item_type::ItemType; -use crate::html::render::{plain_summary_line, shorten}; +use crate::html::render::{plain_text_summary, shorten}; use crate::html::render::{Generic, IndexItem, IndexItemFunctionType, RenderType, TypeWithKind}; /// Indicates where an external crate can be found. @@ -78,7 +78,7 @@ pub fn build_index(krate: &clean::Crate, cache: &mut Cache) -> String { ty: item.type_(), name: item.name.clone().unwrap(), path: fqp[..fqp.len() - 1].join("::"), - desc: shorten(plain_summary_line(item.doc_value())), + desc: shorten(plain_text_summary(item.doc_value())), parent: Some(did), parent_idx: None, search_type: get_index_search_type(&item), @@ -127,7 +127,7 @@ pub fn build_index(krate: &clean::Crate, cache: &mut Cache) -> String { let crate_doc = krate .module .as_ref() - .map(|module| shorten(plain_summary_line(module.doc_value()))) + .map(|module| shorten(plain_text_summary(module.doc_value()))) .unwrap_or(String::new()); #[derive(Serialize)] diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs index 15afe9257d1..90206d27781 100644 --- a/src/librustdoc/html/render/mod.rs +++ b/src/librustdoc/html/render/mod.rs @@ -1506,6 +1506,7 @@ impl Context { } } + /// Construct a map of items shown in the sidebar to a plain-text summary of their docs. fn build_sidebar_items(&self, m: &clean::Module) -> BTreeMap> { // BTreeMap instead of HashMap to get a sorted output let mut map: BTreeMap<_, Vec<_>> = BTreeMap::new(); @@ -1522,7 +1523,7 @@ impl Context { let short = short.to_string(); map.entry(short) .or_default() - .push((myname, Some(plain_summary_line(item.doc_value())))); + .push((myname, Some(plain_text_summary(item.doc_value())))); } if self.shared.sort_modules_alphabetically { @@ -1728,22 +1729,15 @@ fn full_path(cx: &Context, item: &clean::Item) -> String { s } +/// Renders the first paragraph of the given markdown as plain text, making it suitable for +/// contexts like alt-text or the search index. +/// +/// If no markdown is supplied, the empty string is returned. +/// +/// See [`markdown::plain_text_summary`] for further details. #[inline] -crate fn plain_summary_line(s: Option<&str>) -> String { - let s = s.unwrap_or(""); - // This essentially gets the first paragraph of text in one line. - let mut line = s - .lines() - .skip_while(|line| line.chars().all(|c| c.is_whitespace())) - .take_while(|line| line.chars().any(|c| !c.is_whitespace())) - .fold(String::new(), |mut acc, line| { - acc.push_str(line); - acc.push(' '); - acc - }); - // remove final whitespace - line.pop(); - markdown::plain_summary_line(&line[..]) +crate fn plain_text_summary(s: Option<&str>) -> String { + s.map(markdown::plain_text_summary).unwrap_or_default() } crate fn shorten(s: String) -> String { @@ -1800,25 +1794,35 @@ fn render_markdown( ) } +/// Writes a documentation block containing only the first paragraph of the documentation. If the +/// docs are longer, a "Read more" link is appended to the end. fn document_short( w: &mut Buffer, - cx: &Context, item: &clean::Item, link: AssocItemLink<'_>, prefix: &str, is_hidden: bool, ) { if let Some(s) = item.doc_value() { - let markdown = if s.contains('\n') { - format!( - "{} [Read more]({})", - &plain_summary_line(Some(s)), - naive_assoc_href(item, link) - ) - } else { - plain_summary_line(Some(s)) - }; - render_markdown(w, cx, &markdown, item.links(), prefix, is_hidden); + let mut summary_html = MarkdownSummaryLine(s, &item.links()).into_string(); + + if s.contains('\n') { + let link = format!(r#" Read more"#, naive_assoc_href(item, link)); + + if let Some(idx) = summary_html.rfind("

") { + summary_html.insert_str(idx, &link); + } else { + summary_html.push_str(&link); + } + } + + write!( + w, + "
{}{}
", + if is_hidden { " hidden" } else { "" }, + prefix, + summary_html, + ); } else if !prefix.is_empty() { write!( w, @@ -3689,7 +3693,7 @@ fn render_impl( } else if show_def_docs { // In case the item isn't documented, // provide short documentation from the trait. - document_short(w, cx, it, link, "", is_hidden); + document_short(w, it, link, "", is_hidden); } } } else { @@ -3701,7 +3705,7 @@ fn render_impl( } else { document_stability(w, cx, item, is_hidden); if show_def_docs { - document_short(w, cx, item, link, "", is_hidden); + document_short(w, item, link, "", is_hidden); } } } -- cgit 1.4.1-3-g733a5