Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add deny(broken_intra_doc_links) #981

Merged
merged 16 commits into from
Sep 23, 2020
Merged
12 changes: 12 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion tracing-appender/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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,
Expand Down
1 change: 1 addition & 0 deletions tracing-attributes/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
5 changes: 3 additions & 2 deletions tracing-core/src/callsite.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tracing-core/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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))]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

huh, i've never seen this form of cfg_attr with multiple attributes before, does this work?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't even know about it until a while ago, but rust-lang/rust#54862 Implemented cfg_attr with multiple attributes!

#![warn(
missing_debug_implementations,
missing_docs,
Expand Down
2 changes: 1 addition & 1 deletion tracing-error/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
1 change: 1 addition & 0 deletions tracing-flame/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion tracing-futures/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
3 changes: 2 additions & 1 deletion tracing-journald/src/lib.rs
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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};
Expand Down
2 changes: 1 addition & 1 deletion tracing-log/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 2 additions & 0 deletions tracing-macros/src/lib.rs
Original file line number Diff line number Diff line change
@@ -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 {
Expand Down
1 change: 1 addition & 0 deletions tracing-opentelemetry/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
1 change: 1 addition & 0 deletions tracing-serde/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tracing-subscriber/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion tracing-subscriber/src/util.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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>,
}
Expand Down
2 changes: 1 addition & 1 deletion tracing-tower/src/lib.rs
Original file line number Diff line number Diff line change
@@ -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/"
Expand Down
35 changes: 18 additions & 17 deletions tracing/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand All @@ -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",
Expand Down