fix: apply suggestions from review

Co-authored-by: Ben Kimock <kimockb@gmail.com>

library/core/src/hint.rs

@@ -396,9 +396,8 @@ pub fn spin_loop() {
 ///
 /// In practice, `black_box` serves two purposes:
 ///
-/// 1. It prevents the compiler from making optimizations related to the value of the returned
-///    type
-/// 2. It forces the input to be calculated, even if its results are never used
+/// 1. It prevents the compiler from making optimizations related to the value returned by `black_box`
+/// 2. It forces the value passed to `black_box` to be calculated, even if the return value of `black_box` is unused
 ///
 /// ```
 /// use std::hint::black_box;
@@ -407,11 +406,10 @@ pub fn spin_loop() {
 /// let five = 5;
 ///
 /// // The compiler will see this and remove the `* five` call, because it knows that multiplying
-/// // any integer by 0 will result in 0. This is a value optimization: the compiler knows the
-/// // value of `zero` must be 0, and thus can make optimizations related to that.
+/// // any integer by 0 will result in 0.
 /// let c = zero * five;
 ///
-/// // Adding `black_box` here disables the compiler's ability to reason about the value of `zero`.
+/// // Adding `black_box` here disables the compiler's ability to reason about the first operand in the multiplication.
 /// // It is forced to assume that it can be any possible number, so it cannot remove the `* five`
 /// // operation.
 /// let c = black_box(zero) * five;
@@ -444,7 +442,7 @@ pub fn spin_loop() {
 ///
 /// There may be additional situations where you want to wrap the result of a function in
 /// `black_box` to force its execution. This is situational though, and may not have any effect
-/// (such as when the function returns a [`()` unit][unit]).
+/// (such as when the function returns a zero-sized type such as [`()` unit][unit]).
 ///
 /// Note that `black_box` has no effect on how its input is treated, only its output. As such,
 /// expressions passed to `black_box` may still be optimized:
@@ -467,7 +465,7 @@ pub fn spin_loop() {
 /// ```
 /// use std::hint::black_box;
 ///
-/// // No assumptions can be made about either number, so the multiplication is kept.
+/// // No assumptions can be made about either operand, so the multiplication is not optimized out.
 /// let y = black_box(5) * black_box(10);
 /// ```
 #[inline]