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 <eliza@buoyant.io>
Co-authored-by: Joshua Nelson <joshua@yottadb.com>

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,