[WIP] 'Notable Trait Implementations' doc section

library/core/src/fmt/mod.rs

@@ -2097,6 +2097,7 @@ impl<'a> Formatter<'a> {
 }
 
 #[stable(since = "1.2.0", feature = "formatter_write")]
+#[doc(notable_trait)]
 impl Write for Formatter<'_> {
     fn write_str(&mut self, s: &str) -> Result {
         self.buf.write_str(s)

library/std/src/fs.rs

@@ -615,6 +615,7 @@ fn buffer_capacity_required(mut file: &File) -> usize {
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Read for File {
     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
         self.inner.read(buf)
@@ -646,6 +647,7 @@ impl Read for File {
     }
 }
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Write for File {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         self.inner.write(buf)
@@ -671,6 +673,7 @@ impl Seek for File {
     }
 }
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Read for &File {
     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
         self.inner.read(buf)
@@ -702,6 +705,7 @@ impl Read for &File {
     }
 }
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Write for &File {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         self.inner.write(buf)

library/std/src/io/cursor.rs

@@ -439,6 +439,7 @@ fn vec_write_vectored(
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Write for Cursor<&mut [u8]> {
     #[inline]
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
@@ -462,6 +463,7 @@ impl Write for Cursor<&mut [u8]> {
 }
 
 #[stable(feature = "cursor_mut_vec", since = "1.25.0")]
+#[doc(notable_trait)]
 impl Write for Cursor<&mut Vec<u8>> {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         vec_write(&mut self.pos, self.inner, buf)
@@ -483,6 +485,7 @@ impl Write for Cursor<&mut Vec<u8>> {
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Write for Cursor<Vec<u8>> {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         vec_write(&mut self.pos, &mut self.inner, buf)
@@ -504,6 +507,7 @@ impl Write for Cursor<Vec<u8>> {
 }
 
 #[stable(feature = "cursor_box_slice", since = "1.5.0")]
+#[doc(notable_trait)]
 impl Write for Cursor<Box<[u8]>> {
     #[inline]
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {

library/std/src/io/mod.rs

@@ -541,7 +541,6 @@ where
 /// [`std::io`]: self
 /// [`File`]: crate::fs::File
 #[stable(feature = "rust1", since = "1.0.0")]
-#[doc(notable_trait)]
 #[cfg_attr(not(test), rustc_diagnostic_item = "IoRead")]
 pub trait Read {
     /// Pull some bytes from this source into the specified buffer, returning
@@ -1351,7 +1350,6 @@ impl<'a> Deref for IoSlice<'a> {
 ///
 /// [`write_all`]: Write::write_all
 #[stable(feature = "rust1", since = "1.0.0")]
-#[doc(notable_trait)]
 #[cfg_attr(not(test), rustc_diagnostic_item = "IoWrite")]
 pub trait Write {
     /// Write a buffer into this writer, returning how many bytes were written.

library/std/src/io/stdio.rs

@@ -398,6 +398,7 @@ impl fmt::Debug for Stdin {
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Read for Stdin {
     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
         self.lock().read(buf)
@@ -429,6 +430,7 @@ impl StdinLock<'_> {
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Read for StdinLock<'_> {
     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
         self.inner.read(buf)
@@ -623,6 +625,7 @@ impl fmt::Debug for Stdout {
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Write for Stdout {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         (&*self).write(buf)
@@ -649,6 +652,7 @@ impl Write for Stdout {
 }
 
 #[stable(feature = "write_mt", since = "1.48.0")]
+#[doc(notable_trait)]
 impl Write for &Stdout {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         self.lock().write(buf)
@@ -675,6 +679,7 @@ impl Write for &Stdout {
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Write for StdoutLock<'_> {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         self.inner.borrow_mut().write(buf)
@@ -825,6 +830,7 @@ impl fmt::Debug for Stderr {
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Write for Stderr {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         (&*self).write(buf)
@@ -851,6 +857,7 @@ impl Write for Stderr {
 }
 
 #[stable(feature = "write_mt", since = "1.48.0")]
+#[doc(notable_trait)]
 impl Write for &Stderr {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         self.lock().write(buf)
@@ -877,6 +884,7 @@ impl Write for &Stderr {
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Write for StderrLock<'_> {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         self.inner.borrow_mut().write(buf)

library/std/src/io/util.rs

@@ -40,6 +40,7 @@ pub const fn empty() -> Empty {
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Read for Empty {
     #[inline]
     fn read(&mut self, _buf: &mut [u8]) -> io::Result<usize> {
@@ -121,6 +122,7 @@ pub const fn repeat(byte: u8) -> Repeat {
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Read for Repeat {
     #[inline]
     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
@@ -215,6 +217,7 @@ pub const fn sink() -> Sink {
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Write for Sink {
     #[inline]
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
@@ -239,6 +242,7 @@ impl Write for Sink {
 }
 
 #[stable(feature = "write_mt", since = "1.48.0")]
+#[doc(notable_trait)]
 impl Write for &Sink {
     #[inline]
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {

library/std/src/net/tcp.rs

@@ -613,6 +613,7 @@ impl TcpStream {
 // `AsRawSocket`/`IntoRawSocket`/`FromRawSocket` on Windows.
 
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Read for TcpStream {
     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
         self.0.read(buf)
@@ -628,6 +629,7 @@ impl Read for TcpStream {
     }
 }
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Write for TcpStream {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         self.0.write(buf)
@@ -647,6 +649,7 @@ impl Write for TcpStream {
     }
 }
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Read for &TcpStream {
     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
         self.0.read(buf)
@@ -662,6 +665,7 @@ impl Read for &TcpStream {
     }
 }
 #[stable(feature = "rust1", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Write for &TcpStream {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         self.0.write(buf)

library/std/src/process.rs

@@ -266,6 +266,7 @@ pub struct ChildStdin {
 // `AsRawHandle`/`IntoRawHandle`/`FromRawHandle` on Windows.
 
 #[stable(feature = "process", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Write for ChildStdin {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         (&*self).write(buf)
@@ -285,6 +286,7 @@ impl Write for ChildStdin {
 }
 
 #[stable(feature = "write_mt", since = "1.48.0")]
+#[doc(notable_trait)]
 impl Write for &ChildStdin {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         self.inner.write(buf)
@@ -349,6 +351,7 @@ pub struct ChildStdout {
 // `AsRawHandle`/`IntoRawHandle`/`FromRawHandle` on Windows.
 
 #[stable(feature = "process", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Read for ChildStdout {
     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
         self.inner.read(buf)
@@ -410,6 +413,7 @@ pub struct ChildStderr {
 // `AsRawHandle`/`IntoRawHandle`/`FromRawHandle` on Windows.
 
 #[stable(feature = "process", since = "1.0.0")]
+#[doc(notable_trait)]
 impl Read for ChildStderr {
     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
         self.inner.read(buf)

src/librustdoc/formats/mod.rs

@@ -3,6 +3,7 @@ crate mod item_type;
 crate mod renderer;
 
 use rustc_hir::def_id::DefId;
+use rustc_span::sym;
 
 crate use renderer::{run_format, FormatRenderer};
 
@@ -37,6 +38,10 @@ impl Impl {
         }
     }
 
+    crate fn is_notable(&self) -> bool {
+        self.impl_item.attrs.has_doc_flag(sym::notable_trait)
+    }
+
     crate fn trait_did(&self) -> Option<DefId> {
         self.inner_impl().trait_.as_ref().map(|t| t.def_id())
     }

src/librustdoc/html/format.rs

@@ -134,10 +134,6 @@ impl Buffer {
         self.into_inner()
     }
 
-    crate fn is_for_html(&self) -> bool {
-        self.for_html
-    }
-
     crate fn reserve(&mut self, additional: usize) {
         self.buffer.reserve(additional)
     }

src/librustdoc/html/render/mod.rs

@@ -713,7 +713,7 @@ fn render_impls(
             let did = i.trait_did().unwrap();
             let provided_trait_methods = i.inner_impl().provided_trait_methods(tcx);
             let assoc_link = AssocItemLink::GotoSource(did.into(), &provided_trait_methods);
-            let mut buffer = if w.is_for_html() { Buffer::html() } else { Buffer::new() };
+            let mut buffer = Buffer::empty_from(w);
             render_impl(
                 &mut buffer,
                 cx,
@@ -1147,20 +1147,36 @@ fn render_assoc_items_inner(
             traits.iter().partition(|t| t.inner_impl().kind.is_auto());
         let (blanket_impl, concrete): (Vec<&&Impl>, _) =
             concrete.into_iter().partition(|t| t.inner_impl().kind.is_blanket());
+        let (notable, concrete): (Vec<&&Impl>, _) = concrete.into_iter().partition(|t| {
+            t.is_notable() || {
+                t.trait_did()
+                    .and_then(|trait_did| cx.cache().traits.get(&trait_did))
+                    .map_or(false, |t| t.is_notable)
+            }
+        });
 
-        let mut impls = Buffer::empty_from(w);
-        render_impls(cx, &mut impls, &concrete, containing_item, true);
-        let impls = impls.into_inner();
-        if !impls.is_empty() {
-            write!(
-                w,
+        if !notable.is_empty() {
+            w.write_str(
+                "<h2 id=\"notable-trait-implementations\" class=\"small-section-header\">\
+                        Notable Trait Implementations\
+                        <a href=\"#notable-trait-implementations\" class=\"anchor\"></a>\
+                    </h2>\
+                    <div id=\"notable-trait-implementations-list\">",
+            );
+            render_impls(cx, w, &notable, containing_item, true);
+            w.write_str("</div>");
+        }
+
+        if !concrete.is_empty() {
+            w.write_str(
                 "<h2 id=\"trait-implementations\" class=\"small-section-header\">\
                      Trait Implementations\
                      <a href=\"#trait-implementations\" class=\"anchor\"></a>\
                  </h2>\
-                 <div id=\"trait-implementations-list\">{}</div>",
-                impls
+                 <div id=\"trait-implementations-list\">",
             );
+            render_impls(cx, w, &concrete, containing_item, true);
+            w.write_str("</div>");
         }
 
         if !synthetic.is_empty() {
@@ -1273,7 +1289,10 @@ fn notable_traits_decl(decl: &clean::FnDecl, cx: &Context<'_>) -> String {
                 if let Some(trait_) = &impl_.trait_ {
                     let trait_did = trait_.def_id();
 
-                    if cx.cache().traits.get(&trait_did).map_or(false, |t| t.is_notable) {
+                    let trait_is_notable =
+                        cx.cache().traits.get(&trait_did).map_or(false, |t| t.is_notable);
+
+                    if trait_is_notable || i.is_notable() {
                         if out.is_empty() {
                             write!(
                                 &mut out,
@@ -2053,15 +2072,32 @@ fn sidebar_assoc_items(cx: &Context<'_>, out: &mut Buffer, it: &clean::Item) {
                 ret
             };
 
-            let (synthetic, concrete): (Vec<&Impl>, Vec<&Impl>) =
-                v.iter().partition::<Vec<_>, _>(|i| i.inner_impl().kind.is_auto());
-            let (blanket_impl, concrete): (Vec<&Impl>, Vec<&Impl>) =
-                concrete.into_iter().partition::<Vec<_>, _>(|i| i.inner_impl().kind.is_blanket());
+            let (synthetic, concrete): (Vec<&Impl>, _) =
+                v.iter().partition(|i| i.inner_impl().kind.is_auto());
+            let (blanket_impl, concrete): (Vec<&Impl>, _) =
+                concrete.into_iter().partition(|i| i.inner_impl().kind.is_blanket());
+            let (notable, concrete): (Vec<&Impl>, _) = concrete.into_iter().partition(|i| {
+                i.is_notable() || {
+                    i.trait_did()
+                        .and_then(|trait_did| cx.cache().traits.get(&trait_did))
+                        .map_or(false, |i| i.is_notable)
+                }
+            });
 
+            let notable_format = format_impls(notable, &mut id_map);
             let concrete_format = format_impls(concrete, &mut id_map);
             let synthetic_format = format_impls(synthetic, &mut id_map);
             let blanket_format = format_impls(blanket_impl, &mut id_map);
 
+            if !notable_format.is_empty() {
+                print_sidebar_block(
+                    out,
+                    "notable-trait-implementations",
+                    "Notable Trait Implementations",
+                    notable_format.iter(),
+                );
+            }
+
             if !concrete_format.is_empty() {
                 print_sidebar_block(
                     out,