Always display first line of impl blocks even when collapsed

Author: GuillaumeGomez

src/librustdoc/html/markdown.rs

@@ -1305,8 +1305,20 @@ impl LangString {
     }
 }
 
-impl Markdown<'_> {
+impl<'a> Markdown<'a> {
     pub fn into_string(self) -> String {
+        // This is actually common enough to special-case
+        if self.content.is_empty() {
+            return String::new();
+        }
+
+        let mut s = String::with_capacity(self.content.len() * 3 / 2);
+        html::push_html(&mut s, self.into_iter());
+
+        s
+    }
+
+    fn into_iter(self) -> CodeBlocks<'a, 'a, impl Iterator<Item = Event<'a>>> {
         let Markdown {
             content: md,
             links,
@@ -1317,30 +1329,21 @@ impl Markdown<'_> {
             heading_offset,
         } = self;
 
-        // This is actually common enough to special-case
-        if md.is_empty() {
-            return String::new();
-        }
-        let mut replacer = |broken_link: BrokenLink<'_>| {
+        let replacer = move |broken_link: BrokenLink<'_>| {
             links
                 .iter()
                 .find(|link| &*link.original_text == &*broken_link.reference)
                 .map(|link| (link.href.as_str().into(), link.tooltip.as_str().into()))
         };
 
-        let p = Parser::new_with_broken_link_callback(md, main_body_opts(), Some(&mut replacer));
+        let p = Parser::new_with_broken_link_callback(md, main_body_opts(), Some(replacer));
         let p = p.into_offset_iter();
 
-        let mut s = String::with_capacity(md.len() * 3 / 2);
-
         let p = HeadingLinks::new(p, None, ids, heading_offset);
         let p = footnotes::Footnotes::new(p);
         let p = LinkReplacer::new(p.map(|(ev, _)| ev), links);
         let p = TableWrapper::new(p);
-        let p = CodeBlocks::new(p, codes, edition, playground);
-        html::push_html(&mut s, p);
-
-        s
+        CodeBlocks::new(p, codes, edition, playground)
     }
 }
 
@@ -1413,6 +1416,52 @@ impl MarkdownItemInfo<'_> {
     }
 }
 
+pub(crate) fn markdown_split_summary_and_content(
+    md: Markdown<'_>,
+) -> (Option<String>, Option<String>) {
+    if md.content.is_empty() {
+        return (None, None);
+    }
+    let mut p = md.into_iter();
+
+    let mut event_level = 0;
+    let mut summary_events = Vec::new();
+    let mut get_next_tag = false;
+
+    let mut end_of_summary = false;
+    while let Some(event) = p.next() {
+        match event {
+            Event::Start(_) => event_level += 1,
+            Event::End(kind) => {
+                event_level -= 1;
+                if event_level == 0 {
+                    // We're back at the "top" so it means we're done with the summary.
+                    end_of_summary = true;
+                    // We surround tables with `<div>` HTML tags so this is a special case.
+                    get_next_tag = kind == TagEnd::Table;
+                }
+            }
+            _ => {}
+        }
+        summary_events.push(event);
+        if end_of_summary {
+            if get_next_tag && let Some(event) = p.next() {
+                summary_events.push(event);
+            }
+            break;
+        }
+    }
+    let mut summary = String::new();
+    html::push_html(&mut summary, summary_events.into_iter());
+    if summary.is_empty() {
+        return (None, None);
+    }
+    let mut content = String::new();
+    html::push_html(&mut content, p);
+
+    if content.is_empty() { (Some(summary), None) } else { (Some(summary), Some(content)) }
+}
+
 impl MarkdownSummaryLine<'_> {
     pub(crate) fn into_string_with_has_more_content(self) -> (String, bool) {
         let MarkdownSummaryLine(md, links) = self;

src/librustdoc/html/render/mod.rs

@@ -75,6 +75,7 @@ use crate::html::format::{
 };
 use crate::html::markdown::{
     HeadingOffset, IdMap, Markdown, MarkdownItemInfo, MarkdownSummaryLine,
+    markdown_split_summary_and_content,
 };
 use crate::html::static_files::SCRAPE_EXAMPLES_HELP_MD;
 use crate::html::{highlight, sources};
@@ -1937,6 +1938,22 @@ fn render_impl(
                 if rendering_params.toggle_open_by_default { " open" } else { "" }
             );
         }
+
+        let (before_dox, after_dox) = i
+            .impl_item
+            .opt_doc_value()
+            .map(|dox| {
+                markdown_split_summary_and_content(Markdown {
+                    content: &*dox,
+                    links: &i.impl_item.links(cx),
+                    ids: &mut cx.id_map,
+                    error_codes: cx.shared.codes,
+                    edition: cx.shared.edition(),
+                    playground: &cx.shared.playground,
+                    heading_offset: HeadingOffset::H4,
+                })
+            })
+            .unwrap_or((None, None));
         render_impl_summary(
             w,
             cx,
@@ -1945,33 +1962,23 @@ fn render_impl(
             rendering_params.show_def_docs,
             use_absolute,
             aliases,
+            &before_dox,
         );
         if toggled {
             w.write_str("</summary>");
         }
 
-        if let Some(ref dox) = i.impl_item.opt_doc_value() {
+        if before_dox.is_some() {
             if trait_.is_none() && impl_.items.is_empty() {
                 w.write_str(
                     "<div class=\"item-info\">\
                          <div class=\"stab empty-impl\">This impl block contains no items.</div>\
                      </div>",
                 );
             }
-            write!(
-                w,
-                "<div class=\"docblock\">{}</div>",
-                Markdown {
-                    content: &*dox,
-                    links: &i.impl_item.links(cx),
-                    ids: &mut cx.id_map,
-                    error_codes: cx.shared.codes,
-                    edition: cx.shared.edition(),
-                    playground: &cx.shared.playground,
-                    heading_offset: HeadingOffset::H4,
-                }
-                .into_string()
-            );
+            if let Some(after_dox) = after_dox {
+                write!(w, "<div class=\"docblock\">{after_dox}</div>");
+            }
         }
         if !default_impl_items.is_empty() || !impl_items.is_empty() {
             w.write_str("<div class=\"impl-items\">");
@@ -2032,6 +2039,7 @@ pub(crate) fn render_impl_summary(
     // This argument is used to reference same type with different paths to avoid duplication
     // in documentation pages for trait with automatic implementations like "Send" and "Sync".
     aliases: &[String],
+    doc: &Option<String>,
 ) {
     let inner_impl = i.inner_impl();
     let id = cx.derive_id(get_id_for_impl(cx.tcx(), i.impl_item.item_id));
@@ -2083,6 +2091,10 @@ pub(crate) fn render_impl_summary(
         );
     }
 
+    if let Some(doc) = doc {
+        write!(w, "<div class=\"docblock\">{doc}</div>");
+    }
+
     w.write_str("</section>");
 }
 

src/librustdoc/html/static/css/rustdoc.css

@@ -2183,6 +2183,29 @@ details.toggle[open] > summary::after {
 	content: "Collapse";
 }
 
+details.toggle:not([open]) > summary .docblock {
+	max-height: calc(1.5em + 0.75em);
+	overflow-y: hidden;
+}
+details.toggle:not([open]) > summary .docblock::after {
+	content: '';
+	position: absolute;
+	bottom: 0;
+	left: 0;
+	right: 0;
+	pointer-events: none;
+	background: linear-gradient(
+		to top,
+		var(--scrape-example-code-wrapper-background-start),
+		var(--scrape-example-code-wrapper-background-end)
+	);
+	height: 0.7em;
+	z-index: 1;
+}
+details.toggle > summary .docblock {
+	margin-top: 0.75em;
+}
+
 /* This is needed in docblocks to have the "▶" element to be on the same line. */
 .docblock summary > * {
 	display: inline-block;