docs: add deny(broken_intra_doc_links) (#981)

## Motivation

In order to get a compiler warning (or error) when links are broken. 
Closes #940

## Solution

- [x] add `deny(broken_intra_doc_links)`
- [x] add a note to the CONTRIBUTING.md documentation on building docs locally

Co-authored-by: Eliza Weisman <[email protected]>
Co-authored-by: Joshua Nelson <[email protected]>

Author: 3 people

CONTRIBUTING.md

@@ -211,6 +211,18 @@ To reduce the effort required to review documentation-related changes,
 be viewed by clicking the `details` link on the
 `netlify/tracing-rs/deploy-preview check` on all pull requests.
 
+### Building Documentation
+
+Tracing's documentation uses nightly-only RustDoc features and lints, like
+`doc(cfg)` and `broken_intra_doc_lints`. These features are enabled by 
+passing `--cfg docsrs` to RustDoc. Therefore, in order to build Tracing's
+documentation the same way it would be built by docs.rs, it's necessary to
+use the following command:
+
+```bash
+RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --no-deps
+```
+
 ### Commits
 
 It is a recommended best practice to keep your changes as logically grouped as

tracing-appender/src/lib.rs

@@ -34,7 +34,7 @@
 //! # }
 //! ```
 //! This creates an hourly rotating file appender that writes to `/some/directory/prefix.log.YYYY-MM-DD-HH`.
-//! [`Rotation::DAILY`] and [`Rotation::NEVER`] are the other available options.
+//! [`Rotation::DAILY`](rolling::Rotation::DAILY) and [`Rotation::NEVER`](rolling::Rotation::NEVER) are the other available options.
 //!
 //! The file appender implements [`std::io::Write`][write]. To be used with [`tracing_subscriber::FmtSubscriber`][fmt_subscriber],
 //! it must be combined with a [`MakeWriter`][make_writer] implementation to be able to record tracing spans/event.
@@ -127,6 +127,7 @@
     html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",
     issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"
 )]
+#![cfg_attr(docsrs, deny(broken_intra_doc_links))]
 #![warn(
     missing_debug_implementations,
     missing_docs,

tracing-attributes/src/lib.rs

@@ -57,6 +57,7 @@
     html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",
     issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"
 )]
+#![cfg_attr(docsrs, deny(broken_intra_doc_links))]
 #![warn(
     missing_debug_implementations,
     missing_docs,

tracing-core/src/callsite.rs

@@ -72,7 +72,7 @@ impl Registry {
 
 /// Trait implemented by callsites.
 ///
-/// These functions are only intended to be called by the [`Registry`] which
+/// These functions are only intended to be called by the callsite registry, which
 /// correctly handles determining the common interest between all subscribers.
 pub trait Callsite: Sync {
     /// Sets the [`Interest`] for this callsite.
@@ -114,11 +114,12 @@ pub struct Identifier(
 /// [`enabled`] is evaluated for every event.
 ///
 /// This function will also re-compute the global maximum level as determined by
-/// the [`Subscriber::max_level_hint`] method. If a [`Subscriber`]
+/// the [`max_level_hint`] method. If a [`Subscriber`]
 /// implementation changes the value returned by its `max_level_hint`
 /// 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

tracing-core/src/lib.rs

@@ -91,7 +91,7 @@
     issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"
 )]
 #![cfg_attr(not(feature = "std"), no_std)]
-#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg), deny(broken_intra_doc_links))]
 #![warn(
     missing_debug_implementations,
     missing_docs,

tracing-error/src/lib.rs

@@ -185,7 +185,7 @@
 //! supported compiler version is not considered a semver breaking change as
 //! long as doing so complies with this policy.
 //!
-#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg), deny(broken_intra_doc_links))]
 #![doc(html_root_url = "https://docs.rs/tracing-error/0.1.2")]
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",

tracing-flame/src/lib.rs

@@ -113,6 +113,7 @@
     html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",
     issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"
 )]
+#![cfg_attr(docsrs, deny(broken_intra_doc_links))]
 #![warn(
     missing_debug_implementations,
     missing_docs,

tracing-futures/src/lib.rs

@@ -101,7 +101,7 @@
     while_true
 )]
 #![cfg_attr(not(feature = "std"), no_std)]
-#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg), deny(broken_intra_doc_links))]
 #[cfg(feature = "std-future")]
 use pin_project::pin_project;
 

tracing-journald/src/lib.rs

@@ -1,6 +1,6 @@
 //! # tracing-journald
 //!
-//! Support for logging [`tracing`][tracing] events natively to [journald],
+//! Support for logging [`tracing`] events natively to [journald],
 //! preserving structured information.
 //!
 //! ## Overview
@@ -36,6 +36,7 @@
     html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",
     issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"
 )]
+#![cfg_attr(docsrs, deny(broken_intra_doc_links))]
 #[cfg(unix)]
 use std::os::unix::net::UnixDatagram;
 use std::{fmt, io, io::Write};

tracing-log/src/lib.rs

@@ -110,7 +110,7 @@
     html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",
     issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"
 )]
-#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg), deny(broken_intra_doc_links))]
 #![warn(
     missing_debug_implementations,
     missing_docs,

tracing-macros/src/lib.rs

@@ -1,3 +1,5 @@
+#![cfg_attr(docsrs, deny(broken_intra_doc_links))]
+
 /// Alias of `dbg!` for avoiding conflicts with the `std::dbg!` macro.
 #[macro_export]
 macro_rules! trace_dbg {

tracing-opentelemetry/src/lib.rs

@@ -95,6 +95,7 @@
     html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",
     issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"
 )]
+#![cfg_attr(docsrs, deny(broken_intra_doc_links))]
 
 /// Implementation of the trace::Layer as a source of OpenTelemetry data.
 mod layer;

tracing-serde/src/lib.rs

@@ -130,6 +130,7 @@
     html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",
     issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"
 )]
+#![cfg_attr(docsrs, deny(broken_intra_doc_links))]
 #![warn(
     missing_debug_implementations,
     // missing_docs, // TODO: add documentation

tracing-subscriber/src/lib.rs

@@ -72,7 +72,7 @@
     html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",
     issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"
 )]
-#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg), deny(broken_intra_doc_links))]
 #![warn(
     missing_debug_implementations,
     missing_docs,

tracing-subscriber/src/util.rs

@@ -79,7 +79,7 @@ where
 
 impl<T> SubscriberInitExt for T where T: Into<Dispatch> {}
 
-/// Error returned by [`try_init`] if a global default subscriber could not be initialized.
+/// Error returned by [`try_init`](SubscriberInitExt::try_init) if a global default subscriber could not be initialized.
 pub struct TryInitError {
     inner: Box<dyn Error + Send + Sync + 'static>,
 }

tracing-tower/src/lib.rs

@@ -1,4 +1,4 @@
-#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg), deny(broken_intra_doc_links))]
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",
     issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"

tracing/src/lib.rs

@@ -30,7 +30,7 @@
 //! ## Spans
 //!
 //! To record the flow of execution through a program, `tracing` introduces the
-//! concept of [spans][span]. Unlike a log line that represents a _moment in
+//! concept of [spans]. Unlike a log line that represents a _moment in
 //! time_, a span represents a _period of time_ with a beginning and an end. When a
 //! program begins executing in a context or performing a unit of work, it
 //! _enters_ that context's span, and when it stops executing in that context,
@@ -817,21 +817,22 @@
 //! long as doing so complies with this policy.
 //!
 //! [`log`]: https://docs.rs/log/0.4.6/log/
-//! [span]: span/index.html
-//! [`Span`]: span/struct.Span.html
-//! [`in_scope`]: span/struct.Span.html#method.in_scope
-//! [`Event`]: struct.Event.html
-//! [event]: struct.Event.html
-//! [`Subscriber`]: subscriber/trait.Subscriber.html
-//! [Subscriber::event]: subscriber/trait.Subscriber.html#tymethod.event
-//! [`enter`]: subscriber/trait.Subscriber.html#tymethod.enter
-//! [`exit`]: subscriber/trait.Subscriber.html#tymethod.exit
-//! [`enabled`]: subscriber/trait.Subscriber.html#tymethod.enabled
-//! [metadata]: struct.Metadata.html
-//! [`field::display`]: field/fn.display.html
-//! [`field::debug`]: field/fn.debug.html
-//! [`set_global_default`]: subscriber/fn.set_global_default.html
-//! [`with_default`]: subscriber/fn.with_default.html
+//! [span]: mod@span
+//! [spans]: mod@span
+//! [`Span`]: span::Span
+//! [`in_scope`]: span::Span::in_scope
+//! [event]: Event
+//! [events]: Event
+//! [`Subscriber`]: subscriber::Subscriber
+//! [Subscriber::event]: subscriber::Subscriber::event
+//! [`enter`]: subscriber::Subscriber::enter
+//! [`exit`]: subscriber::Subscriber::exit
+//! [`enabled`]: subscriber::Subscriber::enabled
+//! [metadata]: Metadata
+//! [`field::display`]: field::display
+//! [`field::debug`]: field::debug
+//! [`set_global_default`]: subscriber::set_global_default
+//! [`with_default`]: subscriber::with_default
 //! [`tokio-rs/tracing`]: https://github.com/tokio-rs/tracing
 //! [`tracing-futures`]: https://crates.io/crates/tracing-futures
 //! [`tracing-subscriber`]: https://crates.io/crates/tracing-subscriber
@@ -844,7 +845,7 @@
 //! [instrument]: https://docs.rs/tracing-attributes/latest/tracing_attributes/attr.instrument.html
 //! [flags]: #crate-feature-flags
 #![cfg_attr(not(feature = "std"), no_std)]
-#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg), deny(broken_intra_doc_links))]
 #![doc(html_root_url = "https://docs.rs/tracing/0.1.20")]
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",