doc(core::panic::Location::caller): clarify semantics with visual example without changing doctests

Author: Paladynee

library/core/src/panic/location.rs

@@ -105,38 +105,72 @@ impl<'a> Location<'a> {
     /// ```standalone_crate
     /// use std::panic::Location;
     ///
-    /// /// Returns the [`Location`] at which it is called.
+    /// /// ```
+    /// ///      |1        |11       |21       |31       |41
+    /// ///    +-|---------|---------|---------|---------|--------
+    /// /// 15 | #[track_caller]
+    /// /// 16 | fn new_location() -> &'static Location<'static> {
+    /// /// 17 |     Location::caller()
+    /// ///    |     ------------------| the value of this expression depends on the caller,
+    /// ///    |                       | since the function is marked #[track_caller]
+    /// /// 18 | }
+    /// /// ```
     /// #[track_caller]
-    /// fn get_caller_location() -> &'static Location<'static> {
+    /// fn new_location() -> &'static Location<'static> {
     ///     Location::caller()
     /// }
     ///
-    /// /// Returns a [`Location`] from within this function's definition.
-    /// fn get_just_one_location() -> &'static Location<'static> {
-    ///     get_caller_location()
+    /// /// ```
+    /// ///      |1  |5    |11       |21       |31       |41       |51
+    /// ///    +-|---|-----|---------|---------|---------|---------|---
+    /// /// 29 | fn constant_location() -> &'static Location<'static> {
+    /// /// 30 |     new_location()
+    /// ///    |     ^ any invocation of constant_location() points here,
+    /// ///    |       no matter the location it is called from
+    /// /// 31 | }
+    /// /// ```
+    /// fn constant_location() -> &'static Location<'static> {
+    ///     new_location()
     /// }
     ///
-    /// let fixed_location = get_just_one_location();
-    /// assert_eq!(fixed_location.file(), file!());
-    /// assert_eq!(fixed_location.line(), 14);
-    /// assert_eq!(fixed_location.column(), 5);
+    /// fn main() {
+    ///     //      |1  |5    |11       |21       |31       |41       |51
+    ///     //    +-|---|-----|---------|---------|---------|---------|---
+    ///     // 29 | fn constant_location() -> &'static Location<'static> {
+    ///     // 30 |     new_location()
+    ///     //    |     ^ `let constant` points here
+    ///     // 31 | }
+    ///     let constant = constant_location();
+    ///     assert_eq!(constant.file(), file!());
+    ///     assert_eq!((constant.line(), constant.column()), (30, 5));
     ///
-    /// // running the same untracked function in a different location gives us the same result
-    /// let second_fixed_location = get_just_one_location();
-    /// assert_eq!(fixed_location.file(), second_fixed_location.file());
-    /// assert_eq!(fixed_location.line(), second_fixed_location.line());
-    /// assert_eq!(fixed_location.column(), second_fixed_location.column());
+    ///     let constant_2 = constant_location();
+    ///     assert_eq!(
+    ///         (constant.file(), constant.line(), constant.column()),
+    ///         (constant_2.file(), constant_2.line(), constant_2.column())
+    ///     );
     ///
-    /// let this_location = get_caller_location();
-    /// assert_eq!(this_location.file(), file!());
-    /// assert_eq!(this_location.line(), 28);
-    /// assert_eq!(this_location.column(), 21);
+    ///     //      |1        |11  |16  |21       |31
+    ///     //    +-|---------|----|----|---------|------
+    ///     // 55 |     let here = new_location();
+    ///     //    |                ^ `let here` points here, as `new_location()` is the callsite
+    ///     // 56 |     assert_eq!(here.file(), file!());
+    ///     let here = new_location();
+    ///     assert_eq!(here.file(), file!());
+    ///     assert_eq!((here.line(), here.column()), (55, 16));
     ///
-    /// // running the tracked function in a different location produces a different value
-    /// let another_location = get_caller_location();
-    /// assert_eq!(this_location.file(), another_location.file());
-    /// assert_ne!(this_location.line(), another_location.line());
-    /// assert_ne!(this_location.column(), another_location.column());
+    ///     //      |1        |11       |21       ||32      |41       |51
+    ///     //    +-|---------|---------|---------||--------|---------|------
+    ///     // 64 |     let yet_another_location = new_location();
+    ///     //    |                                ^ `let yet_another_location` points here
+    ///     // 65 |     assert_eq!(here.file(), yet_another_location.file());
+    ///     let yet_another_location = new_location();
+    ///     assert_eq!(here.file(), yet_another_location.file());
+    ///     assert_ne!(
+    ///         (here.line(), here.column()),
+    ///         (yet_another_location.line(), yet_another_location.column())
+    ///     );
+    /// }
     /// ```
     #[must_use]
     #[stable(feature = "track_caller", since = "1.46.0")]