Add `deny(broken_intra_doc_links)` #981

TaKO8Ki · 2020-09-21T06:48:29Z

Motivation

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

Solution

add deny(broken_intra_doc_links)
add a note to the CONTRIBUTING.md documentation on building docs locally

TaKO8Ki · 2020-09-21T06:54:32Z

Should I add deny(broken_intra_doc_links) all tracing crates?

TaKO8Ki · 2020-09-21T10:20:46Z

Which section of CONTRIBUTING.md should I add a note of the way to build docs locally?

jyn514 · 2020-09-21T12:26:51Z

Should I add deny(broken_intra_doc_links) all tracing crates?

You don't need this to enable intra-doc links, only to make them a hard error. They'll already warn by default if they fail to resolve.

hawkw

this looks good to me overall. i had a couple style nits that i'd prefer to see addressed.

as a follow-up, we should start converting existing URL-based links into intra-doc links whenever possible.

Which section of CONTRIBUTING.md should I add a note of the way to build docs locally?

I would probably add a new subsection under the "Pull Requests" section, maybe titled "Building Documentation" or something similar. I'd probably put this after the "Tests" subsection, so right before the "Commits" subsection.

tracing-core/src/callsite.rs

hawkw · 2020-09-21T16:32:48Z

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))]


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

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

hawkw · 2020-09-21T16:34:33Z

tracing-core/src/callsite.rs

@@ -114,7 +114,7 @@ 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 [`Subscriber::max_level_hint`](crate::Subscriber::max_level_hint) method. If a [`Subscriber`]


elsewhere, we tend to put link references at the end of the doc comment, rather than inline. i have a slight preference for doing this consistently with the newly-added link references, but i'm not going to block merging this on that.

also, we've tried to wrap the doc comments at a consistent column, can we continue doing that with the changes here?

Yes, I can!

we tend to put link references at the end of the doc comment, rather than inline

I've fixed this!

we've tried to wrap the doc comments at a consistent column, can we continue doing that with the changes here?

What exactly do I have to do?

Co-authored-by: Eliza Weisman <eliza@buoyant.io>

…nto broken-intra-doc-links

hawkw · 2020-09-21T20:39:10Z

CONTRIBUTING.md

@@ -211,6 +211,14 @@ 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
+
+If you want to build docs locally, you should do like this.


It would be nice to explain briefly why this is necessary rather than just running cargo doc

hawkw · 2020-09-21T20:39:50Z

tracing/src/lib.rs

 //! This crate provides two feature flags, "log" and "log-always", which will
-//! cause [spans] and [events] to emit `log` records. When the "log" feature is
+//! cause [spans][span] and [events][event] to emit `log` records. When the "log" feature is


Can we wrap this at the same column as the other lines in this comment?

I've fixed this!

tracing/src/lib.rs

jyn514

ok, last comment I promise 😆

tracing/src/lib.rs

Co-authored-by: Joshua Nelson <joshua@yottadb.com>

hawkw

one last suggestion for the CONTRIBUTING.md docs, and then I think this is good to merge!

CONTRIBUTING.md

Co-authored-by: Eliza Weisman <eliza@buoyant.io>

hawkw

looks great! thanks for working on this!

@nagisa

Fixed - Incorrect inlining of `Span::new`, `Span::new_root`, and `Span::new_child_of`, which could result in `dispatcher::get_default` being inlined at the callsite ([#994]) - Regression where using a struct field as a span or event field when other fields on that struct are borrowed mutably would fail to compile ([#987]) Changed - Updated `tracing-core` to 0.1.17 ([#992]) Added - `Instrument` trait and `Instrumented` type for attaching a `Span` to a `Future` ([#808]) - `Copy` implementations for `Level` and `LevelFilter` ([#992]) - Multiple documentation fixes and improvements ([#964], [#980], [#981]) Thanks to @nagisa, and new contributors @securityinsanity, @froydnj, @jyn514 and @TaKO8Ki for contributing to this release! [#994]: #994 [#992]: #992 [#987]: #987 [#980]: #980 [#981]: #981 [#964]: #964 [#808]: #808 Signed-off-by: Eliza Weisman <eliza@buoyant.io>

@nagisa

### Fixed - Incorrect inlining of `Span::new`, `Span::new_root`, and `Span::new_child_of`, which could result in `dispatcher::get_default` being inlined at the callsite ([#994]) - Regression where using a struct field as a span or event field when other fields on that struct are borrowed mutably would fail to compile ([#987]) ### Changed - Updated `tracing-core` to 0.1.17 ([#992]) ### Added - `Instrument` trait and `Instrumented` type for attaching a `Span` to a `Future` ([#808]) - `Copy` implementations for `Level` and `LevelFilter` ([#992]) - Multiple documentation fixes and improvements ([#964], [#980], [#981]) Thanks to @nagisa, and new contributors @securityinsanity, @froydnj, @jyn514 and @TaKO8Ki for contributing to this release! [#994]: #994 [#992]: #992 [#987]: #987 [#980]: #980 [#981]: #981 [#964]: #964 [#808]: #808 Signed-off-by: Eliza Weisman <eliza@buoyant.io>

@nagisa

Fixed - Compiler error when using `#[instrument(err)]` on functions with mutable parameters ([#1167]) - Missing function visibility modifier when using `#[instrument]` with `async-trait` ([#977]) - Multiple documentation fixes and improvements ([#965], [#981], [#1215]) Changed - `tracing-futures` dependency is no longer required when using `#[instrument]` on async functions ([#808]) Thanks to @nagisa, @Txuritan, @TaKO8Ki, and @okready for contributing to this release! [#1167]: #1167 [#977]: #977 [#965]: #965 [#981]: #981 [#1215]: #1215 [#808]: #808

@nagisa

Fixed - Compiler error when using `#[instrument(err)]` on functions with mutable parameters ([#1167]) - Missing function visibility modifier when using `#[instrument]` with `async-trait` ([#977]) - Multiple documentation fixes and improvements ([#965], [#981], [#1215]) Changed - `tracing-futures` dependency is no longer required when using `#[instrument]` on async functions ([#808]) Thanks to @nagisa, @Txuritan, @TaKO8Ki, and @okready for contributing to this release! [#1167]: #1167 [#977]: #977 [#965]: #965 [#981]: #981 [#1215]: #1215 [#808]: #808

@nagisa

### Fixed - Compiler error when using `#[instrument(err)]` on functions with mutable parameters ([#1167]) - Missing function visibility modifier when using `#[instrument]` with `async-trait` ([#977]) - Multiple documentation fixes and improvements ([#965], [#981], [#1215]) ### Changed - `tracing-futures` dependency is no longer required when using `#[instrument]` on async functions ([#808]) Thanks to @nagisa, @Txuritan, @TaKO8Ki, and @okready for contributing to this release! [#1167]: #1167 [#977]: #977 [#965]: #965 [#981]: #981 [#1215]: #1215 [#808]: #808

@nagisa

Fixed - **attributes**: Compiler error when using `#[instrument(err)]` on functions with mutable parameters ([#1167]) - **attributes**: Missing function visibility modifier when using `#[instrument]` with `async-trait` ([#977]) - **attributes** Removed unused `syn` features ([#928]) - **log**: Fixed an issue where the `tracing` macros would generate code for events whose levels are disabled statically by the `log` crate's `static_max_level_XXX` features ([#1175]) - Fixed deprecations and clippy lints ([#1195]) - Several documentation fixes and improvements ([#941], [#965], [#981], [#1146], [#1215]) Changed - **attributes**: `tracing-futures` dependency is no longer required when using `#[instrument]` on async functions ([#808]) - **attributes**: Updated `tracing-attributes` minimum dependency to v0.1.12 ([#1222]) Thanks to @nagisa, @Txuritan, @TaKO8Ki, @okready, and @krojew for contributing to this release!

@nagisa

### Fixed - **attributes**: Compiler error when using `#[instrument(err)]` on functions with mutable parameters ([#1167]) - **attributes**: Missing function visibility modifier when using `#[instrument]` with `async-trait` ([#977]) - **attributes** Removed unused `syn` features ([#928]) - **log**: Fixed an issue where the `tracing` macros would generate code for events whose levels are disabled statically by the `log` crate's `static_max_level_XXX` features ([#1175]) - Fixed deprecations and clippy lints ([#1195]) - Several documentation fixes and improvements ([#941], [#965], [#981], [#1146], [#1215]) ### Changed - **attributes**: `tracing-futures` dependency is no longer required when using `#[instrument]` on async functions ([#808]) - **attributes**: Updated `tracing-attributes` minimum dependency to v0.1.12 ([#1222]) Thanks to @nagisa, @Txuritan, @TaKO8Ki, @okready, and @krojew for contributing to this release!

Changed - Updated `pin-project` dependency to 1.0 ([#1038]) Fixed - Several documentation fixes and improvements ([#832], [#911], [#913], [#941], [#953], [#981]) [#1038]: https://github.com/tokio-rs/tracing/pulls/1038 [#832]: https://github.com/tokio-rs/tracing/pulls/832 [#911]: https://github.com/tokio-rs/tracing/pulls/911 [#913]: https://github.com/tokio-rs/tracing/pulls/913 [#941]: https://github.com/tokio-rs/tracing/pulls/941

# 0.2.5 (February 16, 2021) ### Changed - Updated `pin-project` dependency to 1.0 ([#1038]) ### Fixed - Several documentation fixes and improvements ([#832], [#911], [#913], [#941], [#953], [#981]) [#1038]: https://github.com/tokio-rs/tracing/pulls/1038 [#832]: https://github.com/tokio-rs/tracing/pulls/832 [#911]: https://github.com/tokio-rs/tracing/pulls/911 [#913]: https://github.com/tokio-rs/tracing/pulls/913 [#941]: https://github.com/tokio-rs/tracing/pulls/941 [#953]: https://github.com/tokio-rs/tracing/pulls/953 [#981]: https://github.com/tokio-rs/tracing/pulls/981 Signed-off-by: Eliza Weisman <eliza@buoyant.io>

Added - Re-export the `log` crate so that users can ensure consistent versions ([#602]) - `AsLog` implementation for `tracing::LevelFilter` ([#1248]) - `AsTrace` implementation for `log::LevelFilter` ([#1248]) Fixed - **log-tracer**: Fixed `Log::enabled` implementation for `LogTracer` not calling `Subscriber::enabled` ([#1254]) - **log-tracer**: Fixed `Log::enabled` implementation for `LogTracer` not checking the max level hint ([#1247]) - Several documentation fixes ([#483], [#485], [#537], [#595], [#941], [#981]) [#483]: https://github.com/tokio-rs/tracing/pulls/483 [#485]: https://github.com/tokio-rs/tracing/pulls/485 [#537]: https://github.com/tokio-rs/tracing/pulls/537 [#595]: https://github.com/tokio-rs/tracing/pulls/595 [#605]: https://github.com/tokio-rs/tracing/pulls/604 [#941]: https://github.com/tokio-rs/tracing/pulls/941 [#1247]: https://github.com/tokio-rs/tracing/pulls/1247 [#1248]: https://github.com/tokio-rs/tracing/pulls/1248 [#1254]: https://github.com/tokio-rs/tracing/pulls/1254 Signed-off-by: Eliza Weisman <eliza@buoyant.io>

add deny(broken_intra_doc_links)

4f6bddc

TaKO8Ki requested review from hawkw, yaahc and a team as code owners September 21, 2020 06:48

TaKO8Ki marked this pull request as draft September 21, 2020 06:48

TaKO8Ki added 5 commits September 21, 2020 16:07

add deny(broken_intra_doc_links) to other crates

9ac5195

fix spans and events link

4e11097

fix rotation links

542f431

fix a private struct link

d2bd001

fix a tracing link

4b60c4d

TaKO8Ki changed the title ~~[WIP] Add deny(broken_intra_doc_links)~~ Add deny(broken_intra_doc_links) Sep 21, 2020

TaKO8Ki marked this pull request as ready for review September 21, 2020 09:23

TaKO8Ki requested a review from jtescher as a code owner September 21, 2020 09:23

fix a try_init link

a5a9fbd

TaKO8Ki force-pushed the broken-intra-doc-links branch from 2197443 to a5a9fbd Compare September 21, 2020 09:41

hawkw reviewed Sep 21, 2020

View reviewed changes

TaKO8Ki and others added 4 commits September 22, 2020 01:48

Update tracing-core/src/callsite.rs

66a84e8

Co-authored-by: Eliza Weisman <eliza@buoyant.io>

add Building Documentation subsection

1766a9e

Merge branch 'broken-intra-doc-links' of github.com:TaKO8Ki/tracing i…

58aade4

…nto broken-intra-doc-links

put a link reference

ead12cf

TaKO8Ki requested a review from hawkw September 21, 2020 18:18

hawkw reviewed Sep 21, 2020

View reviewed changes

wrap spans and events

8b902f4

jyn514 reviewed Sep 22, 2020

View reviewed changes

tracing/src/lib.rs Outdated Show resolved Hide resolved

TaKO8Ki added 2 commits September 22, 2020 13:36

fix building documentation

6b112a3

use intra-doc links

56d0753

TaKO8Ki requested a review from hawkw September 22, 2020 05:15

jyn514 reviewed Sep 22, 2020

View reviewed changes

tracing/src/lib.rs Outdated Show resolved Hide resolved

Update tracing/src/lib.rs

6d0ee28

Co-authored-by: Joshua Nelson <joshua@yottadb.com>

hawkw reviewed Sep 22, 2020

View reviewed changes

CONTRIBUTING.md Outdated Show resolved Hide resolved

Update CONTRIBUTING.md

1f54df4

Co-authored-by: Eliza Weisman <eliza@buoyant.io>

TaKO8Ki requested a review from hawkw September 23, 2020 02:44

hawkw approved these changes Sep 23, 2020

View reviewed changes

hawkw merged commit 6f01226 into tokio-rs:master Sep 23, 2020

jyn514 mentioned this pull request Sep 23, 2020

docs: use intra-RustDoc links rather than URLs #940

Closed

hawkw mentioned this pull request Sep 28, 2020

tracing: prepare to release 0.1.21 #997

Merged

hawkw mentioned this pull request Feb 4, 2021

attributes: prepare to release v0.1.12 #1221

Merged

hawkw mentioned this pull request Feb 4, 2021

tracing: prepare to release v0.1.23 #1223

Merged

hawkw mentioned this pull request Feb 16, 2021

futures: prepare to release 0.2.5 #1241

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `deny(broken_intra_doc_links)` #981

Add `deny(broken_intra_doc_links)` #981

TaKO8Ki commented Sep 21, 2020 •

edited

TaKO8Ki commented Sep 21, 2020

TaKO8Ki commented Sep 21, 2020

jyn514 commented Sep 21, 2020

hawkw left a comment

hawkw Sep 21, 2020

TaKO8Ki Sep 21, 2020

hawkw Sep 21, 2020

TaKO8Ki Sep 21, 2020 •

edited

TaKO8Ki Sep 21, 2020 •

edited

TaKO8Ki Sep 21, 2020 •

edited

hawkw Sep 21, 2020

hawkw Sep 21, 2020

TaKO8Ki Sep 22, 2020

jyn514 left a comment

hawkw left a comment

hawkw left a comment

Add deny(broken_intra_doc_links) #981

Add deny(broken_intra_doc_links) #981

Conversation

TaKO8Ki commented Sep 21, 2020 • edited

Motivation

Solution

TaKO8Ki commented Sep 21, 2020

TaKO8Ki commented Sep 21, 2020

jyn514 commented Sep 21, 2020

hawkw left a comment

Choose a reason for hiding this comment

hawkw Sep 21, 2020

Choose a reason for hiding this comment

TaKO8Ki Sep 21, 2020

Choose a reason for hiding this comment

hawkw Sep 21, 2020

Choose a reason for hiding this comment

TaKO8Ki Sep 21, 2020 • edited

Choose a reason for hiding this comment

TaKO8Ki Sep 21, 2020 • edited

Choose a reason for hiding this comment

TaKO8Ki Sep 21, 2020 • edited

Choose a reason for hiding this comment

hawkw Sep 21, 2020

Choose a reason for hiding this comment

hawkw Sep 21, 2020

Choose a reason for hiding this comment

TaKO8Ki Sep 22, 2020

Choose a reason for hiding this comment

jyn514 left a comment

Choose a reason for hiding this comment

hawkw left a comment

Choose a reason for hiding this comment

hawkw left a comment

Choose a reason for hiding this comment

Add `deny(broken_intra_doc_links)` #981

Add `deny(broken_intra_doc_links)` #981

TaKO8Ki commented Sep 21, 2020 •

edited

TaKO8Ki Sep 21, 2020 •

edited

TaKO8Ki Sep 21, 2020 •

edited

TaKO8Ki Sep 21, 2020 •

edited