@@ -105,38 +105,72 @@ impl<'a> Location<'a> {
105105/// ```standalone_crate
106106/// use std::panic::Location;
107107///
108- /// /// Returns the [`Location`] at which it is called.
108+ /// /// ```
109+ /// /// |1 |11 |21 |31 |41
110+ /// /// +-|---------|---------|---------|---------|--------
111+ /// /// 15 | #[track_caller]
112+ /// /// 16 | fn new_location() -> &'static Location<'static> {
113+ /// /// 17 | Location::caller()
114+ /// /// | ------------------| the value of this expression depends on the caller,
115+ /// /// | | since the function is marked #[track_caller]
116+ /// /// 18 | }
117+ /// /// ```
109118/// #[track_caller]
110- /// fn get_caller_location () -> &'static Location<'static> {
119+ /// fn new_location () -> &'static Location<'static> {
111120/// Location::caller()
112121/// }
113122///
114- /// /// Returns a [`Location`] from within this function's definition.
115- /// fn get_just_one_location() -> &'static Location<'static> {
116- /// get_caller_location()
123+ /// /// ```
124+ /// /// |1 |5 |11 |21 |31 |41 |51
125+ /// /// +-|---|-----|---------|---------|---------|---------|---
126+ /// /// 29 | fn constant_location() -> &'static Location<'static> {
127+ /// /// 30 | new_location()
128+ /// /// | ^ any invocation of constant_location() points here,
129+ /// /// | no matter the location it is called from
130+ /// /// 31 | }
131+ /// /// ```
132+ /// fn constant_location() -> &'static Location<'static> {
133+ /// new_location()
117134/// }
118135///
119- /// let fixed_location = get_just_one_location();
120- /// assert_eq!(fixed_location.file(), file!());
121- /// assert_eq!(fixed_location.line(), 14);
122- /// assert_eq!(fixed_location.column(), 5);
136+ /// fn main() {
137+ /// // |1 |5 |11 |21 |31 |41 |51
138+ /// // +-|---|-----|---------|---------|---------|---------|---
139+ /// // 29 | fn constant_location() -> &'static Location<'static> {
140+ /// // 30 | new_location()
141+ /// // | ^ `let constant` points here
142+ /// // 31 | }
143+ /// let constant = constant_location();
144+ /// assert_eq!(constant.file(), file!());
145+ /// assert_eq!((constant.line(), constant.column()), (30, 5));
123146///
124- /// // running the same untracked function in a different location gives us the same result
125- /// let second_fixed_location = get_just_one_location();
126- /// assert_eq!(fixed_location .file(), second_fixed_location.file());
127- /// assert_eq!(fixed_location.line (), second_fixed_location .line());
128- /// assert_eq!(fixed_location.column(), second_fixed_location.column() );
147+ /// let constant_2 = constant_location();
148+ /// assert_eq!(
149+ /// (constant .file(), constant.line(), constant.column()),
150+ /// (constant_2.file (), constant_2 .line(), constant_2.column())
151+ /// );
129152///
130- /// let this_location = get_caller_location();
131- /// assert_eq!(this_location.file(), file!());
132- /// assert_eq!(this_location.line(), 28);
133- /// assert_eq!(this_location.column(), 21);
153+ /// // |1 |11 |16 |21 |31
154+ /// // +-|---------|----|----|---------|------
155+ /// // 55 | let here = new_location();
156+ /// // | ^ `let here` points here, as `new_location()` is the callsite
157+ /// // 56 | assert_eq!(here.file(), file!());
158+ /// let here = new_location();
159+ /// assert_eq!(here.file(), file!());
160+ /// assert_eq!((here.line(), here.column()), (55, 16));
134161///
135- /// // running the tracked function in a different location produces a different value
136- /// let another_location = get_caller_location();
137- /// assert_eq!(this_location.file(), another_location.file());
138- /// assert_ne!(this_location.line(), another_location.line());
139- /// assert_ne!(this_location.column(), another_location.column());
162+ /// // |1 |11 |21 ||32 |41 |51
163+ /// // +-|---------|---------|---------||--------|---------|------
164+ /// // 64 | let yet_another_location = new_location();
165+ /// // | ^ `let yet_another_location` points here
166+ /// // 65 | assert_eq!(here.file(), yet_another_location.file());
167+ /// let yet_another_location = new_location();
168+ /// assert_eq!(here.file(), yet_another_location.file());
169+ /// assert_ne!(
170+ /// (here.line(), here.column()),
171+ /// (yet_another_location.line(), yet_another_location.column())
172+ /// );
173+ /// }
140174/// ```
141175#[ must_use]
142176 #[ stable( feature = "track_caller" , since = "1.46.0" ) ]
0 commit comments