tracing-core: add documentation on DefaultCallsite (#2149)

This adds a small note on the use of `DefaultCallsite` to the
`tracing-core` docs. I wanted to take care of this before publishing a
new `tracing-core` release.

tracing-core/src/callsite.rs

@@ -68,6 +68,22 @@
 //! configuration changes infrequently, it may be more efficient than calling
 //! [`Subscriber::enabled`] frequently.
 //!
+//! # Implementing Callsites
+//!
+//! In most cases, instrumenting code using `tracing` should *not* require
+//! implementing the [`Callsite`] trait directly. When using the [`tracing`
+//! crate's macros][macros] or the [`#[instrument]` attribute][instrument], a
+//! `Callsite` is automatically generated.
+//!
+//! However, code which provides alternative forms of `tracing` instrumentation
+//! may need to interact with the callsite system directly. If
+//! instrumentation-side code needs to produce a `Callsite` to emit spans or
+//! events, the [`DefaultCallsite`] struct provided in this module is a
+//! ready-made `Callsite` implementation that is suitable for most uses. When
+//! possible, the use of `DefaultCallsite` should be preferred over implementing
+//! [`Callsite`] for user types, as `DefaultCallsite` may benefit from
+//! additional performance optimizations.
+//!
 //! [^1]: Returned by the [`Subscriber::register_callsite`][`register_callsite`]
 //!     method.
 //!
@@ -80,6 +96,8 @@
 //! [sometimes]: crate::subscriber::Interest::sometimes
 //! [never]: crate::subscriber::Interest::never
 //! [`Dispatch`]: crate::dispatch::Dispatch
+//! [macros]: https://docs.rs/tracing/latest/tracing/#macros
+//! [instrument]: https://docs.rs/tracing/latest/tracing/attr.instrument.html
 use crate::stdlib::{
     any::TypeId,
     fmt,