docs: switch to intra-doc links in tracing-core (#1010)

## Motivation

This caught multiple broken links in the documentation. Partially
addresses #940.

## Solution

Use intra-doc links so rustdoc will give a loud warning if the
documentation has errors.

Most of these were auto-converted with

```
rg -l '\[.*\]: .*(trait|struct|enum|fn)\..*\.html*' | grep '\.rs$' | xargs sed -i 's#\.\./\(.*\.html\)#super::\1#g; s#\([a-z]\)/\([a-z]\)#\1::\2#g; s#[a-z]\+\.\([a-zA-Z]\+\)\.html#\1#; s/\([a-z]\)#\(ty\)\?method./\1::/; s/#\(ty\)\?method./Self::/'
```

The rest were massaged by hand. In particular
`<dyn Subscriber>::downcast_ref` isn't yet supported by rustdoc and
can't be converted.

Author: jyn514

tracing-core/src/callsite.rs

@@ -38,20 +38,20 @@ struct Registry {
 pub trait Callsite: Sync {
     /// Sets the [`Interest`] for this callsite.
     ///
-    /// [`Interest`]: ../subscriber/struct.Interest.html
+    /// [`Interest`]: super::subscriber::Interest
     fn set_interest(&self, interest: Interest);
 
     /// Returns the [metadata] associated with the callsite.
     ///
-    /// [metadata]: ../metadata/struct.Metadata.html
+    /// [metadata]: super::metadata::Metadata
     fn metadata(&self) -> &Metadata<'_>;
 }
 
 /// Uniquely identifies a [`Callsite`]
 ///
 /// Two `Identifier`s are equal if they both refer to the same callsite.
 ///
-/// [`Callsite`]: ../callsite/trait.Callsite.html
+/// [`Callsite`]: super::callsite::Callsite
 #[derive(Clone)]
 pub struct Identifier(
     /// **Warning**: The fields on this type are currently `pub` because it must
@@ -92,11 +92,11 @@ pub struct Registration<T = &'static dyn Callsite> {
 /// implementation at runtime, then it **must** call this function after that
 /// value changes, in order for the change to be reflected.
 ///
-/// [`max_level_hint`]: ../subscriber/trait.Subscriber.html#method.max_level_hint
-/// [`Callsite`]: ../callsite/trait.Callsite.html
-/// [`enabled`]: ../subscriber/trait.Subscriber.html#tymethod.enabled
-/// [`Interest::sometimes()`]: ../subscriber/struct.Interest.html#method.sometimes
-/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
+/// [`max_level_hint`]: super::subscriber::Subscriber::max_level_hint
+/// [`Callsite`]: super::callsite::Callsite
+/// [`enabled`]: super::subscriber::Subscriber::enabled
+/// [`Interest::sometimes()`]: super::subscriber::Interest::sometimes
+/// [`Subscriber`]: super::subscriber::Subscriber
 pub fn rebuild_interest_cache() {
     let mut dispatchers = REGISTRY.dispatchers.lock().unwrap();
     let callsites = &REGISTRY.callsites;

tracing-core/src/dispatcher.rs

@@ -113,11 +113,10 @@
 //! </div>
 //! <div class="example-wrap" style="display:inline-block">
 //! <pre class="ignore" style="white-space:normal;font:inherit;">
-//! <strong>Note</strong>:the thread-local scoped dispatcher
-//! (<a href="#fn.with_default"><code>with_default</code></a>) requires the
-//! Rust standard library. <code>no_std</code> users should use
-//! <a href="#fn.set_global_default"><code>set_global_default</code></a>
-//! instead.
+//!
+//! **Note**: the thread-local scoped dispatcher ([`with_default`]) requires the
+//! Rust standard library. `no_std` users should use [`set_global_default`] instead.
+//!
 //! </pre></div>
 //!
 //! ## Accessing the Default Subscriber
@@ -126,12 +125,6 @@
 //! [`get_default`] function, which executes a closure with a reference to the
 //! currently default `Dispatch`. This is used primarily by `tracing`
 //! instrumentation.
-//!
-//! [`Subscriber`]: struct.Subscriber.html
-//! [`with_default`]: fn.with_default.html
-//! [`set_global_default`]: fn.set_global_default.html
-//! [`get_default`]: fn.get_default.html
-//! [`Dispatch`]: struct.Dispatch.html
 use crate::{
     callsite, span,
     subscriber::{self, Subscriber},
@@ -154,8 +147,6 @@ use crate::stdlib::{
 };
 
 /// `Dispatch` trace data to a [`Subscriber`].
-///
-/// [`Subscriber`]: trait.Subscriber.html
 #[derive(Clone)]
 pub struct Dispatch {
     subscriber: Arc<dyn Subscriber + Send + Sync>,
@@ -217,14 +208,15 @@ pub struct DefaultGuard(Option<Dispatch>);
 /// <div class="example-wrap" style="display:inline-block">
 /// <pre class="ignore" style="white-space:normal;font:inherit;">
 /// <strong>Note</strong>: This function required the Rust standard library.
-/// <code>no_std</code> users should use <a href="../fn.set_global_default.html">
-/// <code>set_global_default</code></a> instead.
+/// <!-- hack: this whitespace makes rustdoc interpret the next line as markdown again -->
+///
+/// `no_std` users should use [`set_global_default`] instead.
+///
 /// </pre></div>
 ///
-/// [span]: ../span/index.html
-/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
-/// [`Event`]: ../event/struct.Event.html
-/// [`set_global_default`]: ../fn.set_global_default.html
+/// [span]: super::span
+/// [`Subscriber`]: super::subscriber::Subscriber
+/// [`Event`]: super::event::Event
 #[cfg(feature = "std")]
 #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
 pub fn with_default<T>(dispatcher: &Dispatch, f: impl FnOnce() -> T) -> T {
@@ -244,12 +236,11 @@ pub fn with_default<T>(dispatcher: &Dispatch, f: impl FnOnce() -> T) -> T {
 /// </div>
 /// <div class="example-wrap" style="display:inline-block">
 /// <pre class="ignore" style="white-space:normal;font:inherit;">
-/// <strong>Note</strong>: This function required the Rust standard library.
-/// <code>no_std</code> users should use <a href="../fn.set_global_default.html">
-/// <code>set_global_default</code></a> instead.
-/// </pre></div>
 ///
-/// [`set_global_default`]: ../fn.set_global_default.html
+/// **Note**: This function required the Rust standard library.
+/// `no_std` users should use [`set_global_default`] instead.
+///
+/// </pre></div>
 #[cfg(feature = "std")]
 #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
 #[must_use = "Dropping the guard unregisters the dispatcher."]
@@ -276,9 +267,9 @@ pub fn set_default(dispatcher: &Dispatch) -> DefaultGuard {
 /// executables that depend on the library try to set the default later.
 /// </pre></div>
 ///
-/// [span]: ../span/index.html
-/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
-/// [`Event`]: ../event/struct.Event.html
+/// [span]: super::span
+/// [`Subscriber`]: super::subscriber::Subscriber
+/// [`Event`]: super::event::Event
 pub fn set_global_default(dispatcher: Dispatch) -> Result<(), SetGlobalDefaultError> {
     if GLOBAL_INIT.compare_and_swap(UNINITIALIZED, INITIALIZING, Ordering::SeqCst) == UNINITIALIZED
     {
@@ -325,7 +316,7 @@ impl error::Error for SetGlobalDefaultError {}
 /// called while inside of another `get_default`, that closure will be provided
 /// with `Dispatch::none` rather than the previously set dispatcher.
 ///
-/// [dispatcher]: ../dispatcher/struct.Dispatch.html
+/// [dispatcher]: super::dispatcher::Dispatch
 #[cfg(feature = "std")]
 pub fn get_default<T, F>(mut f: F) -> T
 where
@@ -348,7 +339,7 @@ where
 /// called while inside of another `get_default`, that closure will be provided
 /// with `Dispatch::none` rather than the previously set dispatcher.
 ///
-/// [dispatcher]: ../dispatcher/struct.Dispatch.html
+/// [dispatcher]: super::dispatcher::Dispatch
 #[cfg(feature = "std")]
 #[doc(hidden)]
 #[inline(never)]
@@ -363,7 +354,7 @@ pub fn get_current<T>(f: impl FnOnce(&Dispatch) -> T) -> Option<T> {
 
 /// Executes a closure with a reference to the current [dispatcher].
 ///
-/// [dispatcher]: ../dispatcher/struct.Dispatch.html
+/// [dispatcher]: super::dispatcher::Dispatch
 #[cfg(not(feature = "std"))]
 #[doc(hidden)]
 pub fn get_current<T>(f: impl FnOnce(&Dispatch) -> T) -> Option<T> {
@@ -373,7 +364,7 @@ pub fn get_current<T>(f: impl FnOnce(&Dispatch) -> T) -> Option<T> {
 
 /// Executes a closure with a reference to the current [dispatcher].
 ///
-/// [dispatcher]: ../dispatcher/struct.Dispatch.html
+/// [dispatcher]: super::dispatcher::Dispatch
 #[cfg(not(feature = "std"))]
 pub fn get_default<T, F>(mut f: F) -> T
 where
@@ -412,7 +403,7 @@ impl Dispatch {
 
     /// Returns a `Dispatch` that forwards to the given [`Subscriber`].
     ///
-    /// [`Subscriber`]: ../subscriber/trait.Subscriber.html
+    /// [`Subscriber`]: super::subscriber::Subscriber
     pub fn new<S>(subscriber: S) -> Self
     where
         S: Subscriber + Send + Sync + 'static,
@@ -434,8 +425,8 @@ impl Dispatch {
     /// This calls the [`register_callsite`] function on the [`Subscriber`]
     /// that this `Dispatch` forwards to.
     ///
-    /// [`Subscriber`]: ../subscriber/trait.Subscriber.html
-    /// [`register_callsite`]: ../subscriber/trait.Subscriber.html#method.register_callsite
+    /// [`Subscriber`]: super::subscriber::Subscriber
+    /// [`register_callsite`]: super::subscriber::Subscriber::register_callsite
     #[inline]
     pub fn register_callsite(&self, metadata: &'static Metadata<'static>) -> subscriber::Interest {
         self.subscriber.register_callsite(metadata)
@@ -448,9 +439,9 @@ impl Dispatch {
     /// This calls the [`max_level_hint`] function on the [`Subscriber`]
     /// that this `Dispatch` forwards to.
     ///
-    /// [level]: ../struct.Level.html
-    /// [`Subscriber`]: ../subscriber/trait.Subscriber.html
-    /// [`register_callsite`]: ../subscriber/trait.Subscriber.html#method.max_level_hint
+    /// [level]: super::Level
+    /// [`Subscriber`]: super::subscriber::Subscriber
+    /// [`register_callsite`]: super::subscriber::Subscriber::max_level_hint
     // TODO(eliza): consider making this a public API?
     #[inline]
     pub(crate) fn max_level_hint(&self) -> Option<LevelFilter> {
@@ -463,9 +454,9 @@ impl Dispatch {
     /// This calls the [`new_span`] function on the [`Subscriber`] that this
     /// `Dispatch` forwards to.
     ///
-    /// [ID]: ../span/struct.Id.html
-    /// [`Subscriber`]: ../subscriber/trait.Subscriber.html
-    /// [`new_span`]: ../subscriber/trait.Subscriber.html#method.new_span
+    /// [ID]: super::span::Id
+    /// [`Subscriber`]: super::subscriber::Subscriber
+    /// [`new_span`]: super::subscriber::Subscriber::new_span
     #[inline]
     pub fn new_span(&self, span: &span::Attributes<'_>) -> span::Id {
         self.subscriber.new_span(span)
@@ -476,8 +467,8 @@ impl Dispatch {
     /// This calls the [`record`] function on the [`Subscriber`] that this
     /// `Dispatch` forwards to.
     ///
-    /// [`Subscriber`]: ../subscriber/trait.Subscriber.html
-    /// [`record`]: ../subscriber/trait.Subscriber.html#method.record
+    /// [`Subscriber`]: super::subscriber::Subscriber
+    /// [`record`]: super::subscriber::Subscriber::record
     #[inline]
     pub fn record(&self, span: &span::Id, values: &span::Record<'_>) {
         self.subscriber.record(span, values)
@@ -489,8 +480,8 @@ impl Dispatch {
     /// This calls the [`record_follows_from`] function on the [`Subscriber`]
     /// that this `Dispatch` forwards to.
     ///
-    /// [`Subscriber`]: ../subscriber/trait.Subscriber.html
-    /// [`record_follows_from`]: ../subscriber/trait.Subscriber.html#method.record_follows_from
+    /// [`Subscriber`]: super::subscriber::Subscriber
+    /// [`record_follows_from`]: super::subscriber::Subscriber::record_follows_from
     #[inline]
     pub fn record_follows_from(&self, span: &span::Id, follows: &span::Id) {
         self.subscriber.record_follows_from(span, follows)
@@ -502,9 +493,9 @@ impl Dispatch {
     /// This calls the [`enabled`] function on the [`Subscriber`] that this
     /// `Dispatch` forwards to.
     ///
-    /// [metadata]: ../metadata/struct.Metadata.html
-    /// [`Subscriber`]: ../subscriber/trait.Subscriber.html
-    /// [`enabled`]: ../subscriber/trait.Subscriber.html#method.enabled
+    /// [metadata]: super::metadata::Metadata
+    /// [`Subscriber`]: super::subscriber::Subscriber
+    /// [`enabled`]: super::subscriber::Subscriber::enabled
     #[inline]
     pub fn enabled(&self, metadata: &Metadata<'_>) -> bool {
         self.subscriber.enabled(metadata)
@@ -515,9 +506,9 @@ impl Dispatch {
     /// This calls the [`event`] function on the [`Subscriber`] that this
     /// `Dispatch` forwards to.
     ///
-    /// [`Event`]: ../event/struct.Event.html
-    /// [`Subscriber`]: ../subscriber/trait.Subscriber.html
-    /// [`event`]: ../subscriber/trait.Subscriber.html#method.event
+    /// [`Event`]: super::event::Event
+    /// [`Subscriber`]: super::subscriber::Subscriber
+    /// [`event`]: super::subscriber::Subscriber::event
     #[inline]
     pub fn event(&self, event: &Event<'_>) {
         self.subscriber.event(event)
@@ -528,8 +519,8 @@ impl Dispatch {
     /// This calls the [`enter`] function on the [`Subscriber`] that this
     /// `Dispatch` forwards to.
     ///
-    /// [`Subscriber`]: ../subscriber/trait.Subscriber.html
-    /// [`enter`]: ../subscriber/trait.Subscriber.html#method.enter
+    /// [`Subscriber`]: super::subscriber::Subscriber
+    /// [`enter`]: super::subscriber::Subscriber::enter
     #[inline]
     pub fn enter(&self, span: &span::Id) {
         self.subscriber.enter(span);
@@ -540,8 +531,8 @@ impl Dispatch {
     /// This calls the [`exit`] function on the [`Subscriber`] that this
     /// `Dispatch` forwards to.
     ///
-    /// [`Subscriber`]: ../subscriber/trait.Subscriber.html
-    /// [`exit`]: ../subscriber/trait.Subscriber.html#method.exit
+    /// [`Subscriber`]: super::subscriber::Subscriber
+    /// [`exit`]: super::subscriber::Subscriber::exit
     #[inline]
     pub fn exit(&self, span: &span::Id) {
         self.subscriber.exit(span);
@@ -557,10 +548,10 @@ impl Dispatch {
     /// This calls the [`clone_span`] function on the `Subscriber` that this
     /// `Dispatch` forwards to.
     ///
-    /// [span ID]: ../span/struct.Id.html
-    /// [`Subscriber`]: ../subscriber/trait.Subscriber.html
-    /// [`clone_span`]: ../subscriber/trait.Subscriber.html#method.clone_span
-    /// [`new_span`]: ../subscriber/trait.Subscriber.html#method.new_span
+    /// [span ID]: super::span::Id
+    /// [`Subscriber`]: super::subscriber::Subscriber
+    /// [`clone_span`]: super::subscriber::Subscriber::clone_span
+    /// [`new_span`]: super::subscriber::Subscriber::new_span
     #[inline]
     pub fn clone_span(&self, id: &span::Id) -> span::Id {
         self.subscriber.clone_span(&id)
@@ -580,16 +571,17 @@ impl Dispatch {
     ///     <div class="tooltip compile_fail" style="">&#x26a0; &#xfe0f;<span class="tooltiptext">Warning</span></div>
     /// </div>
     /// <div class="example-wrap" style="display:inline-block"><pre class="compile_fail" style="white-space:normal;font:inherit;">
-    /// <strong>Deprecated</strong>: The <a href="#method.try_close"><code>try_close</code></a>
-    /// method is functionally identical, but returns <code>true</code> if the span is now closed.
+    ///
+    /// **Deprecated**: The [`try_close`] method is functionally identical, but returns `true` if the span is now closed.
     /// It should be used instead of this method.
+    ///
     /// </pre></div>
     ///
-    /// [span ID]: ../span/struct.Id.html
-    /// [`Subscriber`]: ../subscriber/trait.Subscriber.html
-    /// [`drop_span`]: ../subscriber/trait.Subscriber.html#method.drop_span
-    /// [`new_span`]: ../subscriber/trait.Subscriber.html#method.new_span
-    /// [`try_close`]: #method.try_close
+    /// [span ID]: super::span::Id
+    /// [`Subscriber`]: super::subscriber::Subscriber
+    /// [`drop_span`]: super::subscriber::Subscriber::drop_span
+    /// [`new_span`]: super::subscriber::Subscriber::new_span
+    /// [`try_close`]: Self::try_close
     #[inline]
     #[deprecated(since = "0.1.2", note = "use `Dispatch::try_close` instead")]
     pub fn drop_span(&self, id: span::Id) {
@@ -608,10 +600,10 @@ impl Dispatch {
     /// This calls the [`try_close`] function on the [`Subscriber`] that this
     ///  `Dispatch` forwards to.
     ///
-    /// [span ID]: ../span/struct.Id.html
-    /// [`Subscriber`]: ../subscriber/trait.Subscriber.html
-    /// [`try_close`]: ../subscriber/trait.Subscriber.html#method.try_close
-    /// [`new_span`]: ../subscriber/trait.Subscriber.html#method.new_span
+    /// [span ID]: super::span::Id
+    /// [`Subscriber`]: super::subscriber::Subscriber
+    /// [`try_close`]: super::subscriber::Subscriber::try_close
+    /// [`new_span`]: super::subscriber::Subscriber::new_span
     #[inline]
     pub fn try_close(&self, id: span::Id) -> bool {
         self.subscriber.try_close(id)
@@ -622,7 +614,7 @@ impl Dispatch {
     /// This calls the [`current`] function on the `Subscriber` that this
     /// `Dispatch` forwards to.
     ///
-    /// [`current`]: ../subscriber/trait.Subscriber.html#method.current
+    /// [`current`]: super::subscriber::Subscriber::current_span
     #[inline]
     pub fn current_span(&self) -> span::Current {
         self.subscriber.current_span()

tracing-core/src/event.rs

@@ -81,7 +81,7 @@ impl<'a> Event<'a> {
 
     /// Visits all the fields on this `Event` with the specified [visitor].
     ///
-    /// [visitor]: ../field/trait.Visit.html
+    /// [visitor]: super::field::Visit
     #[inline]
     pub fn record(&self, visitor: &mut dyn field::Visit) {
         self.fields.record(visitor);
@@ -94,7 +94,7 @@ impl<'a> Event<'a> {
 
     /// Returns [metadata] describing this `Event`.
     ///
-    /// [metadata]: ../struct.Metadata.html
+    /// [metadata]: super::Metadata
     pub fn metadata(&self) -> &'static Metadata<'static> {
         self.metadata
     }