Rollup of 8 pull requests

Cargo.lock

@@ -1280,7 +1280,6 @@ name = "error_index_generator"
 version = "0.0.0"
 dependencies = [
  "rustdoc",
- "walkdir",
 ]
 
 [[package]]

library/alloc/src/collections/btree/node.rs

@@ -318,7 +318,7 @@ impl<BorrowType: marker::BorrowType, K, V, Type> NodeRef<BorrowType, K, V, Type>
     pub fn ascend(
         self,
     ) -> Result<Handle<NodeRef<BorrowType, K, V, marker::Internal>, marker::Edge>, Self> {
-        assert!(BorrowType::PERMITS_TRAVERSAL);
+        let _ = BorrowType::TRAVERSAL_PERMIT;
         // We need to use raw pointers to nodes because, if BorrowType is marker::ValMut,
         // there might be outstanding mutable references to values that we must not invalidate.
         let leaf_ptr: *const _ = Self::as_leaf_ptr(&self);
@@ -1003,7 +1003,7 @@ impl<BorrowType: marker::BorrowType, K, V>
     /// `edge.descend().ascend().unwrap()` and `node.ascend().unwrap().descend()` should
     /// both, upon success, do nothing.
     pub fn descend(self) -> NodeRef<BorrowType, K, V, marker::LeafOrInternal> {
-        assert!(BorrowType::PERMITS_TRAVERSAL);
+        let _ = BorrowType::TRAVERSAL_PERMIT;
         // We need to use raw pointers to nodes because, if BorrowType is
         // marker::ValMut, there might be outstanding mutable references to
         // values that we must not invalidate. There's no worry accessing the
@@ -1666,15 +1666,17 @@ pub mod marker {
     pub struct ValMut<'a>(PhantomData<&'a mut ()>);
 
     pub trait BorrowType {
-        // Whether node references of this borrow type allow traversing
-        // to other nodes in the tree.
-        const PERMITS_TRAVERSAL: bool = true;
+        // If node references of this borrow type allow traversing to other
+        // nodes in the tree, this constant can be evaluated. Thus reading it
+        // serves as a compile-time assertion.
+        const TRAVERSAL_PERMIT: () = ();
     }
     impl BorrowType for Owned {
-        // Traversal isn't needed, it happens using the result of `borrow_mut`.
+        // Reject evaluation, because traversal isn't needed. Instead traversal
+        // happens using the result of `borrow_mut`.
         // By disabling traversal, and only creating new references to roots,
         // we know that every reference of the `Owned` type is to a root node.
-        const PERMITS_TRAVERSAL: bool = false;
+        const TRAVERSAL_PERMIT: () = panic!();
     }
     impl BorrowType for Dying {}
     impl<'a> BorrowType for Immut<'a> {}

library/core/src/task/wake.rs

@@ -71,6 +71,12 @@ impl RawWaker {
 /// pointer of a properly constructed [`RawWaker`] object from inside the
 /// [`RawWaker`] implementation. Calling one of the contained functions using
 /// any other `data` pointer will cause undefined behavior.
+///
+/// These functions must all be thread-safe (even though [`RawWaker`] is
+/// <code>\![Send] + \![Sync]</code>)
+/// because [`Waker`] is <code>[Send] + [Sync]</code>, and thus wakers may be moved to
+/// arbitrary threads or invoked by `&` reference. For example, this means that if the
+/// `clone` and `drop` functions manage a reference count, they must do so atomically.
 #[stable(feature = "futures_api", since = "1.36.0")]
 #[derive(PartialEq, Copy, Clone, Debug)]
 pub struct RawWakerVTable {
@@ -110,6 +116,12 @@ impl RawWakerVTable {
     /// Creates a new `RawWakerVTable` from the provided `clone`, `wake`,
     /// `wake_by_ref`, and `drop` functions.
     ///
+    /// These functions must all be thread-safe (even though [`RawWaker`] is
+    /// <code>\![Send] + \![Sync]</code>)
+    /// because [`Waker`] is <code>[Send] + [Sync]</code>, and thus wakers may be moved to
+    /// arbitrary threads or invoked by `&` reference. For example, this means that if the
+    /// `clone` and `drop` functions manage a reference count, they must do so atomically.
+    ///
     /// # `clone`
     ///
     /// This function will be called when the [`RawWaker`] gets cloned, e.g. when
@@ -157,9 +169,9 @@ impl RawWakerVTable {
     }
 }
 
-/// The `Context` of an asynchronous task.
+/// The context of an asynchronous task.
 ///
-/// Currently, `Context` only serves to provide access to a `&Waker`
+/// Currently, `Context` only serves to provide access to a [`&Waker`](Waker)
 /// which can be used to wake the current task.
 #[stable(feature = "futures_api", since = "1.36.0")]
 pub struct Context<'a> {
@@ -172,15 +184,15 @@ pub struct Context<'a> {
 }
 
 impl<'a> Context<'a> {
-    /// Create a new `Context` from a `&Waker`.
+    /// Create a new `Context` from a [`&Waker`](Waker).
     #[stable(feature = "futures_api", since = "1.36.0")]
     #[must_use]
     #[inline]
     pub fn from_waker(waker: &'a Waker) -> Self {
         Context { waker, _marker: PhantomData }
     }
 
-    /// Returns a reference to the `Waker` for the current task.
+    /// Returns a reference to the [`Waker`] for the current task.
     #[stable(feature = "futures_api", since = "1.36.0")]
     #[must_use]
     #[inline]
@@ -202,7 +214,18 @@ impl fmt::Debug for Context<'_> {
 /// This handle encapsulates a [`RawWaker`] instance, which defines the
 /// executor-specific wakeup behavior.
 ///
-/// Implements [`Clone`], [`Send`], and [`Sync`].
+/// The typical life of a `Waker` is that it is constructed by an executor, wrapped in a
+/// [`Context`], then passed to [`Future::poll()`]. Then, if the future chooses to return
+/// [`Poll::Pending`], it must also store the waker somehow and call [`Waker::wake()`] when
+/// the future should be polled again.
+///
+/// Implements [`Clone`], [`Send`], and [`Sync`]; therefore, a waker may be invoked
+/// from any thread, including ones not in any way managed by the executor. For example,
+/// this might be done to wake a future when a blocking function call completes on another
+/// thread.
+///
+/// [`Future::poll()`]: core::future::Future::poll
+/// [`Poll::Pending`]: core::task::Poll::Pending
 #[repr(transparent)]
 #[stable(feature = "futures_api", since = "1.36.0")]
 pub struct Waker {
@@ -219,18 +242,21 @@ unsafe impl Sync for Waker {}
 impl Waker {
     /// Wake up the task associated with this `Waker`.
     ///
-    /// As long as the runtime keeps running and the task is not finished, it is
-    /// guaranteed that each invocation of `wake` (or `wake_by_ref`) will be followed
-    /// by at least one `poll` of the task to which this `Waker` belongs. This makes
+    /// As long as the executor keeps running and the task is not finished, it is
+    /// guaranteed that each invocation of [`wake()`](Self::wake) (or
+    /// [`wake_by_ref()`](Self::wake_by_ref)) will be followed by at least one
+    /// [`poll()`] of the task to which this `Waker` belongs. This makes
     /// it possible to temporarily yield to other tasks while running potentially
     /// unbounded processing loops.
     ///
     /// Note that the above implies that multiple wake-ups may be coalesced into a
-    /// single `poll` invocation by the runtime.
+    /// single [`poll()`] invocation by the runtime.
     ///
     /// Also note that yielding to competing tasks is not guaranteed: it is the
     /// executor’s choice which task to run and the executor may choose to run the
     /// current task again.
+    ///
+    /// [`poll()`]: crate::future::Future::poll
     #[inline]
     #[stable(feature = "futures_api", since = "1.36.0")]
     pub fn wake(self) {
@@ -250,8 +276,8 @@ impl Waker {
 
     /// Wake up the task associated with this `Waker` without consuming the `Waker`.
     ///
-    /// This is similar to `wake`, but may be slightly less efficient in the case
-    /// where an owned `Waker` is available. This method should be preferred to
+    /// This is similar to [`wake()`](Self::wake), but may be slightly less efficient in
+    /// the case where an owned `Waker` is available. This method should be preferred to
     /// calling `waker.clone().wake()`.
     #[inline]
     #[stable(feature = "futures_api", since = "1.36.0")]
@@ -263,7 +289,7 @@ impl Waker {
         unsafe { (self.waker.vtable.wake_by_ref)(self.waker.data) }
     }
 
-    /// Returns `true` if this `Waker` and another `Waker` have awoken the same task.
+    /// Returns `true` if this `Waker` and another `Waker` would awake the same task.
     ///
     /// This function works on a best-effort basis, and may return false even
     /// when the `Waker`s would awaken the same task. However, if this function

library/std/src/macros.rs

@@ -27,12 +27,23 @@ macro_rules! panic {
 /// necessary to use [`io::stdout().flush()`][flush] to ensure the output is emitted
 /// immediately.
 ///
+/// The `print!` macro will lock the standard output on each call. If you call
+/// `print!` within a hot loop, this behavior may be the bottleneck of the loop.
+/// To avoid this, lock stdout with [`io::stdout().lock()`][lock]:
+/// ```
+/// use std::io::{stdout, Write};
+///
+/// let mut lock = stdout().lock();
+/// write!(lock, "hello world").unwrap();
+/// ```
+///
 /// Use `print!` only for the primary output of your program. Use
 /// [`eprint!`] instead to print error and progress messages.
 ///
 /// [flush]: crate::io::Write::flush
 /// [`println!`]: crate::println
 /// [`eprint!`]: crate::eprint
+/// [lock]: crate::io::Stdout
 ///
 /// # Panics
 ///
@@ -75,11 +86,22 @@ macro_rules! print {
 /// This macro uses the same syntax as [`format!`], but writes to the standard output instead.
 /// See [`std::fmt`] for more information.
 ///
+/// The `println!` macro will lock the standard output on each call. If you call
+/// `println!` within a hot loop, this behavior may be the bottleneck of the loop.
+/// To avoid this, lock stdout with [`io::stdout().lock()`][lock]:
+/// ```
+/// use std::io::{stdout, Write};
+///
+/// let mut lock = stdout().lock();
+/// writeln!(lock, "hello world").unwrap();
+/// ```
+///
 /// Use `println!` only for the primary output of your program. Use
 /// [`eprintln!`] instead to print error and progress messages.
 ///
 /// [`std::fmt`]: crate::fmt
 /// [`eprintln!`]: crate::eprintln
+/// [lock]: crate::io::Stdout
 ///
 /// # Panics
 ///

src/librustdoc/clean/inline.rs

@@ -300,7 +300,7 @@ pub(crate) fn build_impls(
 }
 
 /// `parent_module` refers to the parent of the re-export, not the original item
-fn merge_attrs(
+pub(crate) fn merge_attrs(
     cx: &mut DocContext<'_>,
     parent_module: Option<DefId>,
     old_attrs: Attrs<'_>,

src/librustdoc/clean/types.rs

@@ -482,7 +482,7 @@ impl Item {
         cx: &mut DocContext<'_>,
         cfg: Option<Arc<Cfg>>,
     ) -> Item {
-        trace!("name={:?}, def_id={:?}", name, def_id);
+        trace!("name={:?}, def_id={:?} cfg={:?}", name, def_id, cfg);
 
         // Primitives and Keywords are written in the source code as private modules.
         // The modules need to be private so that nobody actually uses them, but the
@@ -801,6 +801,31 @@ impl ItemKind {
             | KeywordItem => [].iter(),
         }
     }
+
+    /// Returns `true` if this item does not appear inside an impl block.
+    pub(crate) fn is_non_assoc(&self) -> bool {
+        matches!(
+            self,
+            StructItem(_)
+                | UnionItem(_)
+                | EnumItem(_)
+                | TraitItem(_)
+                | ModuleItem(_)
+                | ExternCrateItem { .. }
+                | FunctionItem(_)
+                | TypedefItem(_)
+                | OpaqueTyItem(_)
+                | StaticItem(_)
+                | ConstantItem(_)
+                | TraitAliasItem(_)
+                | ForeignFunctionItem(_)
+                | ForeignStaticItem(_)
+                | ForeignTypeItem
+                | MacroItem(_)
+                | ProcMacroItem(_)
+                | PrimitiveItem(_)
+        )
+    }
 }
 
 #[derive(Clone, Debug)]

src/librustdoc/html/render/mod.rs

@@ -191,12 +191,6 @@ impl StylePath {
     }
 }
 
-fn write_srclink(cx: &Context<'_>, item: &clean::Item, buf: &mut Buffer) {
-    if let Some(l) = cx.src_href(item) {
-        write!(buf, "<a class=\"srclink\" href=\"{}\">source</a>", l)
-    }
-}
-
 #[derive(Debug, Eq, PartialEq, Hash)]
 struct ItemEntry {
     url: String,
@@ -522,7 +516,14 @@ fn portability(item: &clean::Item, parent: Option<&clean::Item>) -> Option<Strin
         (cfg, _) => cfg.as_deref().cloned(),
     };
 
-    debug!("Portability {:?} - {:?} = {:?}", item.cfg, parent.and_then(|p| p.cfg.as_ref()), cfg);
+    debug!(
+        "Portability {:?} {:?} (parent: {:?}) - {:?} = {:?}",
+        item.name,
+        item.cfg,
+        parent,
+        parent.and_then(|p| p.cfg.as_ref()),
+        cfg
+    );
 
     Some(format!("<div class=\"stab portability\">{}</div>", cfg?.render_long_html()))
 }
@@ -840,12 +841,13 @@ fn assoc_method(
 /// Note that it is possible for an unstable function to be const-stable. In that case, the span
 /// will include the const-stable version, but no stable version will be emitted, as a natural
 /// consequence of the above rules.
-fn render_stability_since_raw(
+fn render_stability_since_raw_with_extra(
     w: &mut Buffer,
     ver: Option<Symbol>,
     const_stability: Option<ConstStability>,
     containing_ver: Option<Symbol>,
     containing_const_ver: Option<Symbol>,
+    extra_class: &str,
 ) -> bool {
     let stable_version = ver.filter(|inner| !inner.is_empty() && Some(*inner) != containing_ver);
 
@@ -893,12 +895,30 @@ fn render_stability_since_raw(
     }
 
     if !stability.is_empty() {
-        write!(w, r#"<span class="since" title="{}">{}</span>"#, title, stability);
+        write!(w, r#"<span class="since{extra_class}" title="{title}">{stability}</span>"#);
     }
 
     !stability.is_empty()
 }
 
+#[inline]
+fn render_stability_since_raw(
+    w: &mut Buffer,
+    ver: Option<Symbol>,
+    const_stability: Option<ConstStability>,
+    containing_ver: Option<Symbol>,
+    containing_const_ver: Option<Symbol>,
+) -> bool {
+    render_stability_since_raw_with_extra(
+        w,
+        ver,
+        const_stability,
+        containing_ver,
+        containing_const_ver,
+        "",
+    )
+}
+
 fn render_assoc_item(
     w: &mut Buffer,
     item: &clean::Item,
@@ -1681,23 +1701,29 @@ fn render_rightside(
         RenderMode::Normal => (item.const_stability(tcx), containing_item.const_stable_since(tcx)),
         RenderMode::ForDeref { .. } => (None, None),
     };
+    let src_href = cx.src_href(item);
+    let has_src_ref = src_href.is_some();
 
     let mut rightside = Buffer::new();
-    let has_stability = render_stability_since_raw(
+    let has_stability = render_stability_since_raw_with_extra(
         &mut rightside,
         item.stable_since(tcx),
         const_stability,
         containing_item.stable_since(tcx),
         const_stable_since,
+        if has_src_ref { "" } else { " rightside" },
     );
-    let mut srclink = Buffer::empty_from(w);
-    write_srclink(cx, item, &mut srclink);
-    if has_stability && !srclink.is_empty() {
-        rightside.write_str(" · ");
+    if let Some(l) = src_href {
+        if has_stability {
+            write!(rightside, " · <a class=\"srclink\" href=\"{}\">source</a>", l)
+        } else {
+            write!(rightside, "<a class=\"srclink rightside\" href=\"{}\">source</a>", l)
+        }
     }
-    rightside.push_buffer(srclink);
-    if !rightside.is_empty() {
+    if has_stability && has_src_ref {
         write!(w, "<span class=\"rightside\">{}</span>", rightside.into_inner());
+    } else {
+        w.push_buffer(rightside);
     }
 }