Improved description

Author: x17jiri

library/core/src/hint.rs

@@ -512,11 +512,23 @@ pub const fn must_use<T>(value: T) -> T {
     value
 }
 
-/// Hints to the compiler that branch condition is likely to be true.
+/// Hints to the compiler that a branch condition is likely to be true.
 /// Returns the value passed to it.
 ///
 /// It can be used with `if` or boolean `match` expressions.
 ///
+/// When used outside of a branch condition, it may still work if there is a branch close by, but
+/// it is not guaranteed to have any effect.
+///
+/// It can also be applied to parts of expressions, such as `likely(a) && unlikely(b)`, or to
+/// compound expressions, such as `likely(a && b)`. When applied to compound expressions, it has
+/// the following effect:
+/// ```
+///     likely(!a) => !unlikely(a)
+///     likely(a && b) => likely(a) && likely(b)
+///     likely(a || b) => a || likely(b)
+/// ```
+///
 /// # Examples
 ///
 /// ```
@@ -534,20 +546,42 @@ pub const fn must_use<T>(value: T) -> T {
 ///         true => println!("this branch is likely to be taken"),
 ///         false => println!("this branch is unlikely to be taken"),
 ///     }
+///
+///     // Use outside of a branch condition. This may still work if there is a branch close by,
+///     // but it is not guaranteed to have any effect
+///     let cond = likely(x != 0);
+///     if cond {
+///         println!("this branch is likely to be taken");
+///     }
 /// }
 /// ```
+///
+///
+
 #[unstable(feature = "likely_unlikely", issue = "26179")]
 #[rustc_nounwind]
 #[inline(always)]
 pub const fn likely(b: bool) -> bool {
     crate::intrinsics::likely(b)
 }
 
-/// Hints to the compiler that the branch condition is unlikely to be true.
+/// Hints to the compiler that a branch condition is unlikely to be true.
 /// Returns the value passed to it.
 ///
 /// It can be used with `if` or boolean `match` expressions.
 ///
+/// When used outside of a branch condition, it may still work if there is a branch close by, but
+/// it is not guaranteed to have any effect.
+///
+/// It can also be applied to parts of expressions, such as `likely(a) && unlikely(b)`, or to
+/// compound expressions, such as `unlikely(a && b)`. When applied to compound expressions, it has
+/// the following effect:
+/// ```
+///     unlikely(!a) => !likely(a)
+///     unlikely(a && b) => a && unlikely(b)
+///     unlikely(a || b) => unlikely(a) || unlikely(b)
+/// ```
+///
 /// # Examples
 ///
 /// ```
@@ -565,6 +599,13 @@ pub const fn likely(b: bool) -> bool {
 ///         true => println!("this branch is unlikely to be taken"),
 ///         false => println!("this branch is likely to be taken"),
 ///     }
+///
+///     // Use outside of a branch condition. This may still work if there is a branch close by,
+///     // but it is not guaranteed to have any effect
+///     let cond = unlikely(x != 0);
+///     if cond {
+///         println!("this branch is likely to be taken");
+///     }
 /// }
 /// ```
 #[unstable(feature = "likely_unlikely", issue = "26179")]