From 38e179769e096fe9d42729447dbe444ef2cf9a57 Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Tue, 17 May 2016 06:50:39 +0530 Subject: [PATCH 1/4] rustdoc: Add doc snippets for trait impls, with a read more link Fixes #33672 --- src/librustdoc/html/render.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/librustdoc/html/render.rs b/src/librustdoc/html/render.rs index 005e25b07d42d..fc91fd2ac62a7 100644 --- a/src/librustdoc/html/render.rs +++ b/src/librustdoc/html/render.rs @@ -1657,6 +1657,17 @@ fn document(w: &mut fmt::Formatter, cx: &Context, item: &clean::Item) -> fmt::Re Ok(()) } +fn document_short(w: &mut fmt::Formatter, item: &clean::Item, link: AssocItemLink) -> fmt::Result { + if let Some(s) = item.doc_value() { + write!(w, "
{}", Markdown(&plain_summary_line(Some(s))))?; + if s.contains('\n') { + write!(w, "Read more", naive_assoc_href(item, link))?; + } + write!(w, "
")?; + } + Ok(()) +} + fn item_module(w: &mut fmt::Formatter, cx: &Context, item: &clean::Item, items: &[clean::Item]) -> fmt::Result { document(w, cx, item)?; @@ -2609,6 +2620,7 @@ fn render_impl(w: &mut fmt::Formatter, cx: &Context, i: &Impl, link: AssocItemLi if !is_default_item && (!is_static || render_static) { document(w, cx, item) } else { + document_short(w, item, link)?; Ok(()) } } From 8e94b045087292574c53f6c9a1d8d624c4f3c66d Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Tue, 17 May 2016 07:31:16 +0530 Subject: [PATCH 2/4] rustdoc: Support short doc fallback for non-default items --- src/librustdoc/html/render.rs | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/src/librustdoc/html/render.rs b/src/librustdoc/html/render.rs index fc91fd2ac62a7..d12486d7e2911 100644 --- a/src/librustdoc/html/render.rs +++ b/src/librustdoc/html/render.rs @@ -2565,8 +2565,9 @@ fn render_impl(w: &mut fmt::Formatter, cx: &Context, i: &Impl, link: AssocItemLi } fn doctraititem(w: &mut fmt::Formatter, cx: &Context, item: &clean::Item, - link: AssocItemLink, render_static: bool, is_default_item: bool, - outer_version: Option<&str>) -> fmt::Result { + link: AssocItemLink, render_static: bool, + is_default_item: bool, outer_version: Option<&str>, + trait_: Option<&clean::Trait>) -> fmt::Result { let shortty = shortty(item); let name = item.name.as_ref().unwrap(); @@ -2618,16 +2619,33 @@ fn render_impl(w: &mut fmt::Formatter, cx: &Context, i: &Impl, link: AssocItemLi } if !is_default_item && (!is_static || render_static) { - document(w, cx, item) + + if item.doc_value().is_some() { + document(w, cx, item) + } else { + // In case the item isn't documented, + // provide short documentation from the trait + if let Some(t) = trait_ { + if let Some(it) = t.items.iter() + .find(|i| i.name == item.name) { + document_short(w, it, link)?; + } + } + Ok(()) + } } else { document_short(w, item, link)?; Ok(()) } } + let traits = &cache().traits; + let trait_ = i.trait_did().and_then(|did| traits.get(&did)); + write!(w, "
")?; for trait_item in &i.inner_impl().items { - doctraititem(w, cx, trait_item, link, render_header, false, outer_version)?; + doctraititem(w, cx, trait_item, link, render_header, + false, outer_version, trait_)?; } fn render_default_items(w: &mut fmt::Formatter, @@ -2645,17 +2663,15 @@ fn render_impl(w: &mut fmt::Formatter, cx: &Context, i: &Impl, link: AssocItemLi let assoc_link = AssocItemLink::GotoSource(did, &i.provided_trait_methods); doctraititem(w, cx, trait_item, assoc_link, render_static, true, - outer_version)?; + outer_version, None)?; } Ok(()) } // If we've implemented a trait, then also emit documentation for all // default items which weren't overridden in the implementation block. - if let Some(did) = i.trait_did() { - if let Some(t) = cache().traits.get(&did) { - render_default_items(w, cx, t, &i.inner_impl(), render_header, outer_version)?; - } + if let Some(t) = trait_ { + render_default_items(w, cx, t, &i.inner_impl(), render_header, outer_version)?; } write!(w, "
")?; Ok(()) From 74633b08e057d62fcd2c221c305fe854c4189f04 Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Wed, 18 May 2016 23:57:13 +0530 Subject: [PATCH 3/4] Move read more link to same line --- src/librustdoc/html/render.rs | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/src/librustdoc/html/render.rs b/src/librustdoc/html/render.rs index d12486d7e2911..e37cb1878d0fd 100644 --- a/src/librustdoc/html/render.rs +++ b/src/librustdoc/html/render.rs @@ -1659,11 +1659,12 @@ fn document(w: &mut fmt::Formatter, cx: &Context, item: &clean::Item) -> fmt::Re fn document_short(w: &mut fmt::Formatter, item: &clean::Item, link: AssocItemLink) -> fmt::Result { if let Some(s) = item.doc_value() { - write!(w, "
{}", Markdown(&plain_summary_line(Some(s))))?; - if s.contains('\n') { - write!(w, "Read more", naive_assoc_href(item, link))?; - } - write!(w, "
")?; + let markdown = if s.contains('\n') { + format!("{} [Read more]({})", &plain_summary_line(Some(s)), naive_assoc_href(item, link)) + } else { + format!("{}", &plain_summary_line(Some(s))) + }; + write!(w, "
{}
", Markdown(&markdown))?; } Ok(()) } From 9ce018bafbda6f1d8484adf4796a48e5cf9093bb Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Thu, 19 May 2016 00:07:58 +0530 Subject: [PATCH 4/4] Update tests --- src/librustdoc/html/render.rs | 32 +++++++++++++++++--------------- src/test/rustdoc/manual_impl.rs | 25 +++++++++++++++++++------ 2 files changed, 36 insertions(+), 21 deletions(-) diff --git a/src/librustdoc/html/render.rs b/src/librustdoc/html/render.rs index e37cb1878d0fd..7b626dbc75054 100644 --- a/src/librustdoc/html/render.rs +++ b/src/librustdoc/html/render.rs @@ -1660,7 +1660,8 @@ fn document(w: &mut fmt::Formatter, cx: &Context, item: &clean::Item) -> fmt::Re fn document_short(w: &mut fmt::Formatter, item: &clean::Item, link: AssocItemLink) -> fmt::Result { 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)) + format!("{} [Read more]({})", + &plain_summary_line(Some(s)), naive_assoc_href(item, link)) } else { format!("{}", &plain_summary_line(Some(s))) }; @@ -2619,25 +2620,26 @@ fn render_impl(w: &mut fmt::Formatter, cx: &Context, i: &Impl, link: AssocItemLi _ => panic!("can't make docs for trait item with name {:?}", item.name) } - if !is_default_item && (!is_static || render_static) { + if !is_static || render_static { + if !is_default_item { - if item.doc_value().is_some() { - document(w, cx, item) - } else { - // In case the item isn't documented, - // provide short documentation from the trait - if let Some(t) = trait_ { - if let Some(it) = t.items.iter() - .find(|i| i.name == item.name) { - document_short(w, it, link)?; + if item.doc_value().is_some() { + document(w, cx, item)?; + } else { + // In case the item isn't documented, + // provide short documentation from the trait + if let Some(t) = trait_ { + if let Some(it) = t.items.iter() + .find(|i| i.name == item.name) { + document_short(w, it, link)?; + } } } - Ok(()) + } else { + document_short(w, item, link)?; } - } else { - document_short(w, item, link)?; - Ok(()) } + Ok(()) } let traits = &cache().traits; diff --git a/src/test/rustdoc/manual_impl.rs b/src/test/rustdoc/manual_impl.rs index 5eccf97bb5f6f..befd3161ac486 100644 --- a/src/test/rustdoc/manual_impl.rs +++ b/src/test/rustdoc/manual_impl.rs @@ -21,13 +21,24 @@ pub trait T { fn b_method(&self) -> usize { self.a_method() } + + /// Docs associated with the trait c_method definition. + /// + /// There is another line + fn c_method(&self) -> usize { + self.a_method() + } } // @has manual_impl/struct.S1.html '//*[@class="trait"]' 'T' // @has - '//*[@class="docblock"]' 'Docs associated with the S1 trait implementation.' // @has - '//*[@class="docblock"]' 'Docs associated with the S1 trait a_method implementation.' // @!has - '//*[@class="docblock"]' 'Docs associated with the trait a_method definition.' -// @!has - '//*[@class="docblock"]' 'Docs associated with the trait b_method definition.' +// @has - '//*[@class="docblock"]' 'Docs associated with the trait b_method definition.' +// @has - '//*[@class="docblock"]' 'Docs associated with the trait b_method definition.' +// @has - '//*[@class="docblock"]' 'Docs associated with the trait c_method definition.' +// @!has - '//*[@class="docblock"]' 'There is another line' +// @has - '//*[@class="docblock"]' 'Read more' pub struct S1(usize); /// Docs associated with the S1 trait implementation. @@ -41,9 +52,11 @@ impl T for S1 { // @has manual_impl/struct.S2.html '//*[@class="trait"]' 'T' // @has - '//*[@class="docblock"]' 'Docs associated with the S2 trait implementation.' // @has - '//*[@class="docblock"]' 'Docs associated with the S2 trait a_method implementation.' -// @has - '//*[@class="docblock"]' 'Docs associated with the S2 trait b_method implementation.' +// @has - '//*[@class="docblock"]' 'Docs associated with the S2 trait c_method implementation.' // @!has - '//*[@class="docblock"]' 'Docs associated with the trait a_method definition.' -// @!has - '//*[@class="docblock"]' 'Docs associated with the trait b_method definition.' +// @!has - '//*[@class="docblock"]' 'Docs associated with the trait c_method definition.' +// @has - '//*[@class="docblock"]' 'Docs associated with the trait b_method definition.' +// @!has - '//*[@class="docblock"]' 'Read more' pub struct S2(usize); /// Docs associated with the S2 trait implementation. @@ -53,8 +66,8 @@ impl T for S2 { self.0 } - /// Docs associated with the S2 trait b_method implementation. - fn b_method(&self) -> usize { + /// Docs associated with the S2 trait c_method implementation. + fn c_method(&self) -> usize { 5 } } @@ -62,7 +75,7 @@ impl T for S2 { // @has manual_impl/struct.S3.html '//*[@class="trait"]' 'T' // @has - '//*[@class="docblock"]' 'Docs associated with the S3 trait implementation.' // @has - '//*[@class="docblock"]' 'Docs associated with the S3 trait b_method implementation.' -// @!has - '//*[@class="docblock"]' 'Docs associated with the trait a_method definition.' +// @has - '//*[@class="docblock"]' 'Docs associated with the trait a_method definition.' pub struct S3(usize); /// Docs associated with the S3 trait implementation.