From d8d8669439bd9e636b9209733c24c32063cc611d Mon Sep 17 00:00:00 2001 From: pierzchalski Date: Thu, 14 Apr 2016 13:57:01 +1000 Subject: [PATCH 1/3] Delegate whether to print docblocks to 'document' Add test to check this resolves #24838 and #26871. --- src/librustdoc/html/render.rs | 9 ++++----- src/test/rustdoc/manual_impl.rs | 26 ++++++++++++++++++++++++++ 2 files changed, 30 insertions(+), 5 deletions(-) create mode 100644 src/test/rustdoc/manual_impl.rs diff --git a/src/librustdoc/html/render.rs b/src/librustdoc/html/render.rs index c5850089578cd..58901dcb38065 100644 --- a/src/librustdoc/html/render.rs +++ b/src/librustdoc/html/render.rs @@ -2540,11 +2540,10 @@ 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) } - match link { - AssocItemLink::Anchor if !is_static || render_static => { - document(w, cx, item) - }, - _ => Ok(()), + if !is_static || render_static { + document(w, cx, item) + } else { + Ok(()) } } diff --git a/src/test/rustdoc/manual_impl.rs b/src/test/rustdoc/manual_impl.rs new file mode 100644 index 0000000000000..540cf58d38ebe --- /dev/null +++ b/src/test/rustdoc/manual_impl.rs @@ -0,0 +1,26 @@ +// Copyright 2015 The Rust Project Developers. See the COPYRIGHT +// file at the top-level directory of this distribution and at +// http://rust-lang.org/COPYRIGHT. +// +// Licensed under the Apache License, Version 2.0 or the MIT license +// , at your +// option. This file may not be copied, modified, or distributed +// except according to those terms. + +pub trait T { + fn a_method(&self) -> usize; +} + +// @has manual_impl/struct.S.html '//*[@class="trait"]' 'T' +// @has - '//*[@class="docblock"]' 'Docs associated with the trait implementation.' +// @has - '//*[@class="docblock"]' 'Docs associated with the trait method implementation.' +pub struct S(usize); + +/// Docs associated with the trait implementation. +impl T for S { + /// Docs associated with the trait method implementation. + fn a_method(&self) -> usize { + self.0 + } +} From d95ca2822cdc67ddec96d16533e23a10d6bfd136 Mon Sep 17 00:00:00 2001 From: pierzchalski Date: Fri, 15 Apr 2016 13:13:55 +1000 Subject: [PATCH 2/3] Add tests against weird provided/required method behaviour In `test/rustdoc/manual_impl.rs` there are now three structs: * S1 implements and documents required method `a_method`. * S2 implements and documents `a_method` as well as provided method `b_method`. * S3 implements `a_method` and `b_method`, but only documents `b_method`. For a struct, we want the rendered trait impls to include documentation if and only if it appears on the trait implementation itself (since users can just go to the trait definition for anything not covered in the impl docs). This means we expect: * S1, S2, and S3 to all include top-level trait impl docs. * S1, S2, and S3 to exclude all trait definition docs. * S1 to show impl docs for `a_method`. * S2 to show impl docs for `a_method` and `b_method`. * S3 to show impl docs for `b_method`. These tests cover those cases. --- src/test/rustdoc/manual_impl.rs | 62 +++++++++++++++++++++++++++++---- 1 file changed, 55 insertions(+), 7 deletions(-) diff --git a/src/test/rustdoc/manual_impl.rs b/src/test/rustdoc/manual_impl.rs index 540cf58d38ebe..6675a0fd43b4e 100644 --- a/src/test/rustdoc/manual_impl.rs +++ b/src/test/rustdoc/manual_impl.rs @@ -8,19 +8,67 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +/// Docs associated with the trait definition. pub trait T { + /// Docs associated with the trait a_method definition. fn a_method(&self) -> usize; + + /// Docs associated with the trait b_method definition. + fn b_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.' +pub struct S1(usize); + +/// Docs associated with the S1 trait implementation. +impl T for S1 { + /// Docs associated with the S1 trait a_method implementation. + fn a_method(&self) -> usize { + self.0 + } +} + +// @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 trait a_method definition.' +// @!has - '//*[@class="docblock"]' 'Docs associated with the trait b_method definition.' +pub struct S2(usize); + +/// Docs associated with the S2 trait implementation. +impl T for S2 { + /// Docs associated with the S2 trait a_method implementation. + fn a_method(&self) -> usize { + self.0 + } + + /// Docs associated with the S2 trait b_method implementation. + fn b_method(&self) -> usize { + 5 + } } -// @has manual_impl/struct.S.html '//*[@class="trait"]' 'T' -// @has - '//*[@class="docblock"]' 'Docs associated with the trait implementation.' -// @has - '//*[@class="docblock"]' 'Docs associated with the trait method implementation.' -pub struct S(usize); +// @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.' +pub struct S3(usize); -/// Docs associated with the trait implementation. -impl T for S { - /// Docs associated with the trait method implementation. +/// Docs associated with the S3 trait implementation. +impl T for S3 { fn a_method(&self) -> usize { self.0 } + + /// Docs associated with the S3 trait b_method implementation. + fn b_method(&self) -> usize { + 5 + } } From ec5e0f81cf54ca287e6652923e1bf46f4fc1c783 Mon Sep 17 00:00:00 2001 From: pierzchalski Date: Fri, 15 Apr 2016 14:41:54 +1000 Subject: [PATCH 3/3] Add flag for whether an item is default or not. We don't want to render default item docs but previously `doctraititem` naively delegated to the trait definition in those cases. Updated tests to also check that this doesn't strip default item docs from the trait definition. --- src/librustdoc/html/render.rs | 8 ++++---- src/test/rustdoc/manual_impl.rs | 4 ++++ 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/src/librustdoc/html/render.rs b/src/librustdoc/html/render.rs index 58901dcb38065..ba1fbc75c18a3 100644 --- a/src/librustdoc/html/render.rs +++ b/src/librustdoc/html/render.rs @@ -2489,7 +2489,7 @@ 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, + link: AssocItemLink, render_static: bool, is_default_item: bool, outer_version: Option<&str>) -> fmt::Result { let shortty = shortty(item); let name = item.name.as_ref().unwrap(); @@ -2540,7 +2540,7 @@ 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_static || render_static { + if !is_default_item && (!is_static || render_static) { document(w, cx, item) } else { Ok(()) @@ -2549,7 +2549,7 @@ fn render_impl(w: &mut fmt::Formatter, cx: &Context, i: &Impl, link: AssocItemLi write!(w, "
")?; for trait_item in &i.impl_.items { - doctraititem(w, cx, trait_item, link, render_header, outer_version)?; + doctraititem(w, cx, trait_item, link, render_header, false, outer_version)?; } fn render_default_items(w: &mut fmt::Formatter, @@ -2566,7 +2566,7 @@ fn render_impl(w: &mut fmt::Formatter, cx: &Context, i: &Impl, link: AssocItemLi let did = i.trait_.as_ref().unwrap().def_id().unwrap(); let assoc_link = AssocItemLink::GotoSource(did, &i.provided_trait_methods); - doctraititem(w, cx, trait_item, assoc_link, render_static, + doctraititem(w, cx, trait_item, assoc_link, render_static, true, outer_version)?; } Ok(()) diff --git a/src/test/rustdoc/manual_impl.rs b/src/test/rustdoc/manual_impl.rs index 6675a0fd43b4e..5eccf97bb5f6f 100644 --- a/src/test/rustdoc/manual_impl.rs +++ b/src/test/rustdoc/manual_impl.rs @@ -8,6 +8,10 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +// @has manual_impl/trait.T.html +// @has - '//*[@class="docblock"]' 'Docs associated with the trait definition.' +// @has - '//*[@class="docblock"]' 'Docs associated with the trait a_method definition.' +// @has - '//*[@class="docblock"]' 'Docs associated with the trait b_method definition.' /// Docs associated with the trait definition. pub trait T { /// Docs associated with the trait a_method definition.