diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 181b3e8474..e9254458ca 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/tracing-appender/src/lib.rs b/tracing-appender/src/lib.rs index 5b6fbf8ae4..cd3ea6110e 100644 --- a/tracing-appender/src/lib.rs +++ b/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, diff --git a/tracing-attributes/src/lib.rs b/tracing-attributes/src/lib.rs index 58698a7723..c674095d3b 100644 --- a/tracing-attributes/src/lib.rs +++ b/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, diff --git a/tracing-core/src/callsite.rs b/tracing-core/src/callsite.rs index f6904befda..5e48473e15 100644 --- a/tracing-core/src/callsite.rs +++ b/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 diff --git a/tracing-core/src/lib.rs b/tracing-core/src/lib.rs index 49ba35ea91..bba9987605 100644 --- a/tracing-core/src/lib.rs +++ b/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, diff --git a/tracing-error/src/lib.rs b/tracing-error/src/lib.rs index 21c5f4b1aa..05f367430c 100644 --- a/tracing-error/src/lib.rs +++ b/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", diff --git a/tracing-flame/src/lib.rs b/tracing-flame/src/lib.rs index 5605c2cd60..afeba005d1 100644 --- a/tracing-flame/src/lib.rs +++ b/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, diff --git a/tracing-futures/src/lib.rs b/tracing-futures/src/lib.rs index 262f3b64e9..9dc1afb4b1 100644 --- a/tracing-futures/src/lib.rs +++ b/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; diff --git a/tracing-journald/src/lib.rs b/tracing-journald/src/lib.rs index 27ba6721a5..f9ddee668d 100644 --- a/tracing-journald/src/lib.rs +++ b/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}; diff --git a/tracing-log/src/lib.rs b/tracing-log/src/lib.rs index ce97845de3..c4cf239dcc 100644 --- a/tracing-log/src/lib.rs +++ b/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, diff --git a/tracing-macros/src/lib.rs b/tracing-macros/src/lib.rs index 7643f1d831..3a3ccc854f 100644 --- a/tracing-macros/src/lib.rs +++ b/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 { diff --git a/tracing-opentelemetry/src/lib.rs b/tracing-opentelemetry/src/lib.rs index 6fdd43dfbd..b515d66a9a 100644 --- a/tracing-opentelemetry/src/lib.rs +++ b/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; diff --git a/tracing-serde/src/lib.rs b/tracing-serde/src/lib.rs index 9307aa74b4..d98e28b459 100644 --- a/tracing-serde/src/lib.rs +++ b/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 diff --git a/tracing-subscriber/src/lib.rs b/tracing-subscriber/src/lib.rs index bbea61b5c9..0622696852 100644 --- a/tracing-subscriber/src/lib.rs +++ b/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, diff --git a/tracing-subscriber/src/util.rs b/tracing-subscriber/src/util.rs index 4d40bbf320..f6d95c3714 100644 --- a/tracing-subscriber/src/util.rs +++ b/tracing-subscriber/src/util.rs @@ -79,7 +79,7 @@ where impl SubscriberInitExt for T where T: Into {} -/// 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, } diff --git a/tracing-tower/src/lib.rs b/tracing-tower/src/lib.rs index 1c81615f3f..d3975fceb0 100644 --- a/tracing-tower/src/lib.rs +++ b/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/" diff --git a/tracing/src/lib.rs b/tracing/src/lib.rs index 22688d7893..6ae17e085a 100644 --- a/tracing/src/lib.rs +++ b/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",