From 38e179769e096fe9d42729447dbe444ef2cf9a57 Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Tue, 17 May 2016 06:50:39 +0530 Subject: [PATCH 01/13] 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 02/13] 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 03/13] 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 519cc8280cef3f809149080b44b9d66f967368aa Mon Sep 17 00:00:00 2001 From: Steven Burns Date: Thu, 19 May 2016 11:05:13 -0600 Subject: [PATCH 04/13] Book: small improvement to a table to make it clearer --- src/doc/book/the-stack-and-the-heap.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/book/the-stack-and-the-heap.md b/src/doc/book/the-stack-and-the-heap.md index a7b6faccd8d6e..a1f6a065a252b 100644 --- a/src/doc/book/the-stack-and-the-heap.md +++ b/src/doc/book/the-stack-and-the-heap.md @@ -175,6 +175,7 @@ And then `bold()` calls `italic()`: | **2** | **b**|**100**| | **1** | **a**| **5** | | 0 | x | 42 | + Whew! Our stack is growing tall. After `italic()` is over, its frame is deallocated, leaving only `bold()` and @@ -260,8 +261,7 @@ layout of a program which has been running for a while now: | (230) - 3 | | | | (230) - 4 | | 42 | | ... | ... | ... | -| 3 | y | → (230) - 4 | -| 2 | y | 42 | +| 2 | z | → (230) - 4 | | 1 | y | 42 | | 0 | x | → (230) - 1 | From 2fd4e604a46d1175f260a33efdfcacb7b48ed1ff Mon Sep 17 00:00:00 2001 From: Postmodern Date: Thu, 19 May 2016 17:07:29 -0700 Subject: [PATCH 05/13] Clarify the English translation of `?Sized` * It wasn't clear whether `?Sized` meant "not `Sized`" or "`Sized` or not `Sized`". According to #rust IRC, it does indeed mean "`Sized` or not `Sized`". * Use the same language as [Trait std::marker::Sized](https://doc.rust-lang.org/std/marker/trait.Sized.html) about how `Sized` is implicitly bound. --- src/doc/book/unsized-types.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/doc/book/unsized-types.md b/src/doc/book/unsized-types.md index 73b90355e4f1b..d94409a7b827d 100644 --- a/src/doc/book/unsized-types.md +++ b/src/doc/book/unsized-types.md @@ -47,7 +47,7 @@ pointers, can use this `impl`. # ?Sized If you want to write a function that accepts a dynamically sized type, you -can use the special bound, `?Sized`: +can use the special syntax, `?Sized`: ```rust struct Foo { @@ -55,6 +55,5 @@ struct Foo { } ``` -This `?`, read as “T may be `Sized`”, means that this bound is special: it -lets us match more kinds, not less. It’s almost like every `T` implicitly has -`T: Sized`, and the `?` undoes this default. +This `?Sized`, read as “T may or may not be `Sized`”, allowing us to match both constant size and unsized types. +All generic type parameters implicitly have the `Sized` bound, so `?Sized` can be used to opt-out of the implicit bound. From d021d7d7cf3aa222ac5bbca6d0c109e0d1f9a890 Mon Sep 17 00:00:00 2001 From: Postmodern Date: Thu, 19 May 2016 17:17:17 -0700 Subject: [PATCH 06/13] Keep line-width within 80 columns --- src/doc/book/unsized-types.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/doc/book/unsized-types.md b/src/doc/book/unsized-types.md index d94409a7b827d..12864f2067ed4 100644 --- a/src/doc/book/unsized-types.md +++ b/src/doc/book/unsized-types.md @@ -55,5 +55,6 @@ struct Foo { } ``` -This `?Sized`, read as “T may or may not be `Sized`”, allowing us to match both constant size and unsized types. -All generic type parameters implicitly have the `Sized` bound, so `?Sized` can be used to opt-out of the implicit bound. +This `?Sized`, read as “T may or may not be `Sized`”, allowing us to match both +constant size and unsized types. All generic type parameters implicitly have +the `Sized` bound, so `?Sized` can be used to opt-out of the implicit bound. From d8c086b08561b41576e2614ae3b360374ccf993d Mon Sep 17 00:00:00 2001 From: Postmodern Date: Thu, 19 May 2016 17:27:04 -0700 Subject: [PATCH 07/13] Grammar change --- src/doc/book/unsized-types.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/doc/book/unsized-types.md b/src/doc/book/unsized-types.md index 12864f2067ed4..746faeb81b2d8 100644 --- a/src/doc/book/unsized-types.md +++ b/src/doc/book/unsized-types.md @@ -55,6 +55,7 @@ struct Foo { } ``` -This `?Sized`, read as “T may or may not be `Sized`”, allowing us to match both -constant size and unsized types. All generic type parameters implicitly have -the `Sized` bound, so `?Sized` can be used to opt-out of the implicit bound. +This `?Sized`, read as “T may or may not be `Sized`”, which allows us to match +both constant size and unsized types. All generic type parameters implicitly +have the `Sized` bound, so `?Sized` can be used to opt-out of the implicit +bound. From e614bb70c2f662016bdbcc8ef06716849b3ce773 Mon Sep 17 00:00:00 2001 From: "Daniel Campoverde [alx741]" Date: Thu, 19 May 2016 20:14:29 -0500 Subject: [PATCH 08/13] book: ownership: fix typo --- src/doc/book/ownership.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/ownership.md b/src/doc/book/ownership.md index e2e0403b738fa..f445bed015c00 100644 --- a/src/doc/book/ownership.md +++ b/src/doc/book/ownership.md @@ -155,7 +155,7 @@ vector object and its data live in separate memory regions instead of being a single contiguous memory allocation (due to reasons we will not go into at this point of time). These two parts of the vector (the one on the stack and one on the heap) must agree with each other at all times with regards to -things like the length, capacity etc. +things like the length, capacity, etc. When we move `v` to `v2`, Rust actually does a bitwise copy of the vector object `v` into the stack allocation represented by `v2`. This shallow copy From 9ce018bafbda6f1d8484adf4796a48e5cf9093bb Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Thu, 19 May 2016 00:07:58 +0530 Subject: [PATCH 09/13] 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. From bbed89b4e562c7b1f3c7266fe8b35e5db3886dbc Mon Sep 17 00:00:00 2001 From: ggomez Date: Fri, 20 May 2016 15:19:34 +0200 Subject: [PATCH 10/13] Update simd syntax --- src/librustc_typeck/diagnostics.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/librustc_typeck/diagnostics.rs b/src/librustc_typeck/diagnostics.rs index 5f2997a86a9f2..45aec9558feaf 100644 --- a/src/librustc_typeck/diagnostics.rs +++ b/src/librustc_typeck/diagnostics.rs @@ -1002,18 +1002,18 @@ operate on. This will cause an error: ```compile_fail -#![feature(simd)] +#![feature(repr_simd)] -#[simd] +#[repr(simd)] struct Bad; ``` This will not: ``` -#![feature(simd)] +#![feature(repr_simd)] -#[simd] +#[repr(simd)] struct Good(u32); ``` "##, From bf8c070bd5f4ebda0a0958af8b06289c1fd7e70a Mon Sep 17 00:00:00 2001 From: Stefan Schindler Date: Fri, 20 May 2016 00:21:01 +0200 Subject: [PATCH 11/13] Clarify docs for sort(&mut self) --- src/libcollections/slice.rs | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/src/libcollections/slice.rs b/src/libcollections/slice.rs index 0f77ebb3c5745..6321d5924d51a 100644 --- a/src/libcollections/slice.rs +++ b/src/libcollections/slice.rs @@ -779,11 +779,10 @@ impl [T] { core_slice::SliceExt::binary_search_by_key(self, b, f) } - /// Sorts the slice, in place. - /// /// This is equivalent to `self.sort_by(|a, b| a.cmp(b))`. /// - /// This is a stable sort. + /// This sort is stable and `O(n log n)` worst-case but allocates + /// approximately `2 * n` where `n` is the length of `self`. /// /// # Examples /// @@ -804,11 +803,9 @@ impl [T] { /// Sorts the slice, in place, using `key` to extract a key by which to /// order the sort by. /// - /// This sort is `O(n log n)` worst-case and stable, but allocates + /// This sort is stable and `O(n log n)` worst-case but allocates /// approximately `2 * n`, where `n` is the length of `self`. /// - /// This is a stable sort. - /// /// # Examples /// /// ```rust @@ -828,7 +825,7 @@ impl [T] { /// Sorts the slice, in place, using `compare` to compare /// elements. /// - /// This sort is `O(n log n)` worst-case and stable, but allocates + /// This sort is stable and `O(n log n)` worst-case but allocates /// approximately `2 * n`, where `n` is the length of `self`. /// /// # Examples From b9d1e76252f73d4e16eb701a00f34508cbe19323 Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Wed, 11 May 2016 21:01:29 -0400 Subject: [PATCH 12/13] update tracking issue for once_poison The tracking issue for once_poison was noted as #31688 which was closed, so it now points to the new #33577. --- src/libstd/sync/once.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/libstd/sync/once.rs b/src/libstd/sync/once.rs index d8a4a69c73cd3..e9ea465cc9993 100644 --- a/src/libstd/sync/once.rs +++ b/src/libstd/sync/once.rs @@ -101,7 +101,7 @@ unsafe impl Send for Once {} /// State yielded to the `call_once_force` method which can be used to query /// whether the `Once` was previously poisoned or not. -#[unstable(feature = "once_poison", issue = "31688")] +#[unstable(feature = "once_poison", issue = "33577")] pub struct OnceState { poisoned: bool, } @@ -218,7 +218,7 @@ impl Once { /// The closure `f` is yielded a structure which can be used to query the /// state of this `Once` (whether initialization has previously panicked or /// not). - #[unstable(feature = "once_poison", issue = "31688")] + #[unstable(feature = "once_poison", issue = "33577")] pub fn call_once_force(&'static self, f: F) where F: FnOnce(&OnceState) { // same as above, just with a different parameter to `call_inner`. if self.state.load(Ordering::SeqCst) == COMPLETE { @@ -360,7 +360,7 @@ impl OnceState { /// /// Once an initalization routine for a `Once` has panicked it will forever /// indicate to future forced initialization routines that it is poisoned. - #[unstable(feature = "once_poison", issue = "31688")] + #[unstable(feature = "once_poison", issue = "33577")] pub fn poisoned(&self) -> bool { self.poisoned } From 71af58accf8f773a7d410cf947940487f65ae70f Mon Sep 17 00:00:00 2001 From: Postmodern Date: Fri, 20 May 2016 17:47:34 -0700 Subject: [PATCH 13/13] Wording changes * Use "special bound syntax" instead of "special syntax". `?Sized` is technically a "bound", but `?Sized` is specialized syntax that _only_ works with `Sized`, and no other Trait. * Replace "constant size" with "sized". --- src/doc/book/unsized-types.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/doc/book/unsized-types.md b/src/doc/book/unsized-types.md index 746faeb81b2d8..a23470d39fa09 100644 --- a/src/doc/book/unsized-types.md +++ b/src/doc/book/unsized-types.md @@ -47,7 +47,7 @@ pointers, can use this `impl`. # ?Sized If you want to write a function that accepts a dynamically sized type, you -can use the special syntax, `?Sized`: +can use the special bound syntax, `?Sized`: ```rust struct Foo { @@ -56,6 +56,6 @@ struct Foo { ``` This `?Sized`, read as “T may or may not be `Sized`”, which allows us to match -both constant size and unsized types. All generic type parameters implicitly -have the `Sized` bound, so `?Sized` can be used to opt-out of the implicit +both sized and unsized types. All generic type parameters implicitly +have the `Sized` bound, so the `?Sized` can be used to opt-out of the implicit bound.