attributes: update docs for instrument

tracing-attributes/src/lib.rs

@@ -109,12 +109,16 @@ mod expand;
 ///
 /// Additional fields (key-value pairs with arbitrary data) can be passed to
 /// to the generated span through the `fields` argument on the
-/// `#[instrument]` macro. Strings, integers or boolean literals are accepted values
-/// for each field. The name of the field must be a single valid Rust
-/// identifier, nested (dotted) field names are not supported.
+/// `#[instrument]` macro. Strings, integers or boolean literals are accepted
+/// values for each field. The name of the field may be a nested (dotted) field
+/// name.
+///
+/// When an additional field does not include a value,
+/// [`Empty`](tracing-core::field::Empty) will be inserted and this field can be
+/// recoreded later with [`Span::record`](tracing::Span::record).
 ///
 /// Note that overlap between the names of fields and (non-skipped) arguments
-/// will result in a compile error.
+/// will result in an [`Empty`](tracing-core::field::Empty) value.
 ///
 /// # Examples
 /// Instrumenting a function:
@@ -220,6 +224,19 @@ mod expand;
 /// }
 /// ```
 ///
+/// To add additional context not known at the time of the function kall, add a field without a value.
+///
+/// ```
+/// # use tracing::Span;
+/// # use tracing_attributes::instrument;
+/// #[instrument(fields(foo="bar", foo.id))]
+/// fn my_function(arg: usize) {
+///     // ...
+///     Span::current().record("id", 1);
+///     // ...
+/// }
+/// ```
+///
 /// Adding the `ret` argument to `#[instrument]` will emit an event with the function's
 /// return value when the function returns:
 ///