Add #[must_use] to non-mutating verb methods

diff --git a/library/alloc/src/rc.rs b/library/alloc/src/rc.rs
index 2f4a131136e928a20a516527ad3682047b7b9959..4023d7b21ed0bbbd0a0dd025eac44c0466d189a5 100644 (file)
--- a/library/alloc/src/rc.rs
+++ b/library/alloc/src/rc.rs
@@ -2229,6 +2229,8 @@ pub unsafe fn from_raw(ptr: *const T) -> Self {
     ///
     /// assert!(weak_five.upgrade().is_none());
     /// ```
+    #[must_use = "this returns a new `Rc`, \
+                  without modifying the original weak pointer"]
     #[stable(feature = "rc_weak", since = "1.4.0")]
     pub fn upgrade(&self) -> Option<Rc<T>> {
         let inner = self.inner()?;

diff --git a/library/alloc/src/sync.rs b/library/alloc/src/sync.rs
index 1d4216d7d571af24f947a39bc7695773ecd0f8f7..905e3d72a458c65254b8beebd0cf924c9791e783 100644 (file)
--- a/library/alloc/src/sync.rs
+++ b/library/alloc/src/sync.rs
@@ -146,7 +146,7 @@ macro_rules! acquire {
 /// use std::sync::Arc;
 ///
 /// let my_arc = Arc::new(());
-/// Arc::downgrade(&my_arc);
+/// let my_weak = Arc::downgrade(&my_arc);
 /// ```
 ///
 /// `Arc<T>`'s implementations of traits like `Clone` may also be called using
@@ -897,6 +897,8 @@ pub unsafe fn from_raw(ptr: *const T) -> Self {
     ///
     /// let weak_five = Arc::downgrade(&five);
     /// ```
+    #[must_use = "this returns a new `Weak` pointer, \
+                  without modifying the original `Arc`"]
     #[stable(feature = "arc_weak", since = "1.4.0")]
     pub fn downgrade(this: &Self) -> Weak<T> {
         // This Relaxed is OK because we're checking the value in the CAS
@@ -1861,6 +1863,8 @@ impl<T: ?Sized> Weak<T> {
     ///
     /// assert!(weak_five.upgrade().is_none());
     /// ```
+    #[must_use = "this returns a new `Arc`, \
+                  without modifying the original weak pointer"]
     #[stable(feature = "arc_weak", since = "1.4.0")]
     pub fn upgrade(&self) -> Option<Arc<T>> {
         // We use a CAS loop to increment the strong count instead of a

diff --git a/library/core/src/alloc/layout.rs b/library/core/src/alloc/layout.rs
index d4c8ea33501a6a5fb8679f54a05739532bca374d..780f82d8afaee1fbd50b0944123a5fd976aede17 100644 (file)
--- a/library/core/src/alloc/layout.rs
+++ b/library/core/src/alloc/layout.rs
@@ -112,6 +112,8 @@ pub const fn size(&self) -> usize {
     /// The minimum byte alignment for a memory block of this layout.
     #[stable(feature = "alloc_layout", since = "1.28.0")]
     #[rustc_const_stable(feature = "const_alloc_layout", since = "1.50.0")]
+    #[must_use = "this returns the minimum alignment, \
+                  without modifying the layout"]
     #[inline]
     pub const fn align(&self) -> usize {
         self.align_.get()
@@ -229,6 +231,8 @@ pub fn align_to(&self, align: usize) -> Result<Self, LayoutError> {
     /// satisfy this constraint is to ensure `align <= self.align()`.
     #[unstable(feature = "alloc_layout_extra", issue = "55724")]
     #[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")]
+    #[must_use = "this returns the padding needed, \
+                  without modifying the `Layout`"]
     #[inline]
     pub const fn padding_needed_for(&self, align: usize) -> usize {
         let len = self.size();
@@ -262,6 +266,8 @@ pub const fn padding_needed_for(&self, align: usize) -> usize {
     /// This is equivalent to adding the result of `padding_needed_for`
     /// to the layout's current size.
     #[stable(feature = "alloc_layout_manipulation", since = "1.44.0")]
+    #[must_use = "this returns a new `Layout`, \
+                  without modifying the original"]
     #[inline]
     pub fn pad_to_align(&self) -> Layout {
         let pad = self.padding_needed_for(self.align());

diff --git a/library/std/src/path.rs b/library/std/src/path.rs
index a8a79fb9c8fbb6120c592184d975a699396386b7..008baa2443f50a7d59b0c46bfbf42d9458e2f1dc 100644 (file)
--- a/library/std/src/path.rs
+++ b/library/std/src/path.rs
@@ -2511,6 +2511,8 @@ pub fn iter(&self) -> Iter<'_> {
     /// println!("{}", path.display());
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
+    #[must_use = "this does not display the path, \
+                  it returns an object that can be displayed"]
     #[inline]
     pub fn display(&self) -> Display<'_> {
         Display { path: self }