Document #[track_caller].

Author: anp

src/attributes.md

@@ -219,6 +219,7 @@ The following is an index of all built-in attributes.
   - [`cold`] — Hint that a function is unlikely to be called.
   - [`no_builtins`] — Disables use of certain built-in functions.
   - [`target_feature`] — Configure platform-specific code generation.
+  - [`track_caller`] - Pass the parent call location to `std::panic::Location::caller()`.
 - Documentation
   - `doc` — Specifies documentation. See [The Rustdoc Book] for more
     information. [Doc comments] are transformed into `doc` attributes.
@@ -291,6 +292,7 @@ The following is an index of all built-in attributes.
 [`should_panic`]: attributes/testing.md#the-should_panic-attribute
 [`target_feature`]: attributes/codegen.md#the-target_feature-attribute
 [`test`]: attributes/testing.md#the-test-attribute
+[`track_caller`]: attributes/codegen.md#the-track_caller-attribute
 [`type_length_limit`]: attributes/limits.md#the-type_length_limit-attribute
 [`used`]: abi.md#the-used-attribute
 [`warn`]: attributes/diagnostics.md#lint-check-attributes

src/attributes/codegen.md

@@ -140,6 +140,25 @@ feature detection on the x86 platforms.
 > may be enabled or disabled for an entire crate with the
 > [`-C target-feature`] flag.
 
+## The `track_caller` attribute
+
+The `track_caller` attribute applies to function declarations and indicates to the compiler that the
+attributed function's generated code should have an implicit `&'static core::panic::Location`
+argument which is populated by its caller. If the caller of the attributed function is also
+annotated with `#[track_caller]`, then the attributed function should receive the location
+its caller received, and so on.
+
+An implementation of `core::intrinsics::caller_location` returns this implicit argument if called
+from a function with the attribute. Otherwise it returns the location at which the intrinsic itself
+was called.
+
+Creating a function pointer to a function with `#[track_caller]` creates a shim which passes the
+location at which the attributed function is defined. The pointer then refers to this shim,
+preventing unsoundness or the implicit ABI from leaking into the function pointer's type.
+
+In a const context, the attribute does not affect function ABI and instead informs the const
+evaluator to continue walking up the stack when probing for the topmost caller location.
+
 [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
 [`-C target-cpu`]: ../../rustc/codegen-options/index.html#target-cpu
 [`-C target-feature`]: ../../rustc/codegen-options/index.html#target-feature