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,28 @@ 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, allowing code within the function to
+observe the callsite of the topmost `track_caller`-attributed function in the attributed function's
+callers. If the attributed function itself is called by an unattributed function, then the
+attributed function observes its own callsite. If the attributed function is called by another
+attributed function, then code within the callee observes the callsite of the caller, and so on.
+
+> Note: `rustc` implements the `core::intrinsics::caller_location` intrinsic for observing the
+> callsite of a function with `#[track_caller]`, wrapped by `core::panic::Location::caller` for
+> general use.
+
+Coercing a function with `#[track_caller]` to a function pointer creates a shim which appears to
+observers to have been called at the attributed function's definition site.
+
+> Note: Rules around shims for function pointers are necessary because `rustc` implements
+> `track_caller` in a codegen context by appending an implicit parameter to the function ABI, but
+> this would be unsound for an indirect call because the parameter is not a part of the function's
+> type and a given function pointer type may or may not refer to a function with the attribute. The
+> creation of a shim hides the implicit parameter from callers of the function pointer, preserving
+> soundness.
+
 [_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