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

docs: more intra-doc links #2077

Merged
merged 4 commits into from
Apr 19, 2022
Merged

Conversation

ben0x539
Copy link
Contributor

@ben0x539 ben0x539 commented Apr 15, 2022

Motivation

Intra-doc links are neat and get checked by rustdoc. #940.

Solution

Continuing from #2068, this changes more links in doc comments from full URLs to intra-doc links and cleans up some redundant [`Foo`]: Foo-style links, partly with the help of cargo intraconv which I've since been pointed at.

Primarily,

  • #foo links turned into Blah::foo
  • intra-doc links for stuff in std etc
  • intra-doc links to non-optional dependencies

For the latter I've tried to be conservative so that people who build their own docs with some features disabled don't get broken links (but possibly missed some since this was kinda manual, and there were already warnings for unresolved references without some features). For std I have not been conservative even though std is optional in places as there were already a bunch of intra-doc links to std.

... also it deleted some redundant ones, and it got some things wrong,
and it was gonna delete some of the cross-crate docs.rs links we can't
do as intra-doc links so I passed `--no-favored`.
Note that this adds some more broken intra doc links when building
without std support, but that was already a thing and I expect people
who build their own docs without std support can handle it.

This time I gave up on sed and used ruby.

    find -name '*.rs' -exec ruby -i -p blah.rb {} +

with

    $_.gsub!(%r{
        https://doc\.rust-lang\.org/
        (?: stable/)?
        ((?:core | std | alloc)(?:/\S+?)*)
        /(\w+)\.(\w+)\.html}x
    ) {
      path, kind, name = $~.captures
      suffix = case kind
        when 'method' then '()'
        when 'macro' then '!'
        else ''
      end
      r = [path.gsub('/', '::'), '::', name, suffix].join
      STDERR.puts [path, kind, name, suffix, r].inspect
      r
    }
    $_.gsub!(%r{
        https://doc\.rust-lang\.org/
        (?: stable/)?
        ((?: core | std | alloc)(?:/\S+?)*)
        /(?:
          index\.html
          | $
          | (?= \#)
         )}x
    ) {
      path, _ = $~.captures
      r = path.gsub('/', '::')
      STDERR.puts [path, r].inspect
      r
    }
cargo intraconv doesn't seem to get them reliably and also plenty of
links to other crates aren't actually intra-doc because they're in
crates that don't depend (or only dev-depend, or only conditionally
depend) on those crates, so this wasn't very automated.

I tried to only convert docs.rs links to unconditional dependencies to
intra-crate links, but it's possible that some slipped through in either
direction.
@ben0x539 ben0x539 requested review from a team, jtescher, yaahc and hawkw as code owners April 15, 2022 02:13
Copy link
Member

@hawkw hawkw left a comment

Choose a reason for hiding this comment

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

Provided the docs build successfully (which the CI results indicate they do), this looks great to me! Thanks for your continued work on this!

@hawkw hawkw enabled auto-merge (squash) April 19, 2022 17:56
@hawkw hawkw merged commit c8a2bb2 into tokio-rs:v0.1.x Apr 19, 2022
hawkw added a commit that referenced this pull request Apr 21, 2022
# 0.3.0 (April 21, 2022)

This is a breaking release which changes the format in which span fields
are output to `journald`. Previously, span field names were prefixed
with the depth of the span in the current trace tree. However, these
prefixes are unnecessary, as `journald` has built in support for
duplicated field names.

See PR [#1986] for details on this change.

## Changed

- Removed span field prefixes ([#1986])
- Renamed `S{num}_NAME` fields to `SPAN_NAME ([#1986])

### Fixed

- Fixed broken links in documentation ([#2077])

Thanks to @wiktorsikora and @ben0x539 for contributing to this release!

[#1986]: #1986
[#2077]: #2077
hawkw added a commit that referenced this pull request Apr 21, 2022
# 0.3.0 (April 21, 2022)

This is a breaking release which changes the format in which span fields
are output to `journald`. Previously, span field names were prefixed
with the depth of the span in the current trace tree. However, these
prefixes are unnecessary, as `journald` has built in support for
duplicated field names.

See PR [#1986] for details on this change.

## Changed

- Removed span field prefixes ([#1986])
- Renamed `S{num}_NAME` fields to `SPAN_NAME ([#1986])

### Fixed

- Fixed broken links in documentation ([#2077])

Thanks to @wiktorsikora and @ben0x539 for contributing to this release!

[#1986]: #1986
[#2077]: #2077
hawkw added a commit that referenced this pull request Apr 21, 2022
# 0.3.0 (April 21, 2022)

This is a breaking release which changes the format in which span fields
are output to `journald`. Previously, span field names were prefixed
with the depth of the span in the current trace tree. However, these
prefixes are unnecessary, as `journald` has built in support for
duplicated field names.

See PR [#1986] for details on this change.

## Changed

- Removed span field prefixes ([#1986])
- Renamed `S{num}_NAME` fields to `SPAN_NAME ([#1986])

### Fixed

- Fixed broken links in documentation ([#2077])

Thanks to @wiktorsikora and @ben0x539 for contributing to this release!

[#1986]: #1986
[#2077]: #2077
hawkw added a commit that referenced this pull request Apr 21, 2022
# 0.1.3 (April 21st, 2022)

### Added

- **log-tracer**: Added `LogTracer::with_interest_cache` to enable a
 limited form of per-record `Interest` caching for `log` records
 ([#1636])

### Changed

- Updated minimum supported Rust version (MSRV) to Rust 1.49.0 ([#1913])

### Fixed

- **log-tracer**: Fixed `LogTracer` not honoring `tracing` max level
  filters ([#1543])
- Broken links in documentation ([#2068], [#2077])

Thanks to @Millione, @teozkr, @koute, @Folyd, and @ben0x539 for
contributing to this release!

[#1636]: https://github.com/tokio-rs/tracing/pulls/1636
[#1913]: https://github.com/tokio-rs/tracing/pulls/1913
[#1543]: https://github.com/tokio-rs/tracing/pulls/1543
[#2068]: https://github.com/tokio-rs/tracing/pulls/2068
[#2077]: https://github.com/tokio-rs/tracing/pulls/2077
hawkw added a commit that referenced this pull request Apr 21, 2022
# 0.1.3 (April 21st, 2022)

### Added

- **log-tracer**: Added `LogTracer::with_interest_cache` to enable a
 limited form of per-record `Interest` caching for `log` records
 ([#1636])

### Changed

- Updated minimum supported Rust version (MSRV) to Rust 1.49.0 ([#1913])

### Fixed

- **log-tracer**: Fixed `LogTracer` not honoring `tracing` max level
  filters ([#1543])
- Broken links in documentation ([#2068], [#2077])

Thanks to @Millione, @teozkr, @koute, @Folyd, and @ben0x539 for
contributing to this release!

[#1636]: https://github.com/tokio-rs/tracing/pulls/1636
[#1913]: https://github.com/tokio-rs/tracing/pulls/1913
[#1543]: https://github.com/tokio-rs/tracing/pulls/1543
[#2068]: https://github.com/tokio-rs/tracing/pulls/2068
[#2077]: https://github.com/tokio-rs/tracing/pulls/2077

Fixes #1884
Fixes #1664
hawkw added a commit that referenced this pull request Apr 26, 2022
# 0.1.21 (April 26, 2022)

This release adds support for setting explicit parent and follows-from
spans in the `#[instrument]` attribute.

### Added

- `#[instrument(follows_from = ...)]` argument for setting one or more
  follows-from span ([#2093])
- `#[instrument(parent = ...)]` argument for overriding the generated
  span's parent ([#2091])

### Fixed

- Extra braces around `async` blocks in expanded code (causes a Clippy
  warning) ([#2090])
- Broken documentation links ([#2068], [#2077])

Thanks to @jarrodldavis, @ben0x539, and new contributor @jswrenn for
contributing to this release!

[#2093]: #2093
[#2091]: #2091
[#2090]: #2090
[#2077]: #2077
[#2068]: #2068
hawkw added a commit that referenced this pull request Apr 27, 2022
# 0.1.21 (April 26, 2022)

This release adds support for setting explicit parent and follows-from
spans in the `#[instrument]` attribute.

### Added

- `#[instrument(follows_from = ...)]` argument for setting one or more
  follows-from span ([#2093])
- `#[instrument(parent = ...)]` argument for overriding the generated
  span's parent ([#2091])

### Fixed

- Extra braces around `async` blocks in expanded code (causes a Clippy
  warning) ([#2090])
- Broken documentation links ([#2068], [#2077])

Thanks to @jarrodldavis, @ben0x539, and new contributor @jswrenn for
contributing to this release!

[#2093]: #2093
[#2091]: #2091
[#2090]: #2090
[#2077]: #2077
[#2068]: #2068
hawkw added a commit that referenced this pull request Jun 29, 2022
# 0.3.12 (Jun 29, 2022)

This release of `tracing-subscriber` adds a new `Layer::event_enabled`
method, which allows `Layer`s to filter events *after* their field
values are recorded; a `Filter` implementation for `reload::Layer`, to
make using `reload` with per-layer filtering more ergonomic, and
additional inherent method downcasting APIs for the `Layered` type. In
addition, it includes dependency updates, and minor fixes for
documentation and feature flagging.

### Added

- **layer**: `Layer::event_enabled` method, which can be implemented to
  filter events based on their field values (#2008)
- **reload**: `Filter` implementation for `reload::Layer` (#2159)
- **layer**: `Layered::downcast_ref` and `Layered::is` inherent methods
  (#2160)

### Changed

- **parking_lot**: Updated dependency on `parking_lot` to 0.13.0
  (#2143)
- Replaced `lazy_static` dependency with `once_cell` (#2147)

### Fixed

- Don't enable `tracing-core` features by default (#2107)
- Several documentation link and typo fixes (#2064, #2068, #2077,
  #2161, #1088)

Thanks to @ben0x539, @jamesmunns, @georgemp, @james7132, @jswrenn,
@CAD97, and @guswynn for contributing to this release!
hawkw added a commit that referenced this pull request Jun 29, 2022
# 0.3.12 (Jun 29, 2022)

This release of `tracing-subscriber` adds a new `Layer::event_enabled`
method, which allows `Layer`s to filter events *after* their field
values are recorded; a `Filter` implementation for `reload::Layer`, to
make using `reload` with per-layer filtering more ergonomic, and
additional inherent method downcasting APIs for the `Layered` type. In
addition, it includes dependency updates, and minor fixes for
documentation and feature flagging.

### Added

- **layer**: `Layer::event_enabled` method, which can be implemented to
  filter events based on their field values (#2008)
- **reload**: `Filter` implementation for `reload::Layer` (#2159)
- **layer**: `Layered::downcast_ref` and `Layered::is` inherent methods
  (#2160)

### Changed

- **parking_lot**: Updated dependency on `parking_lot` to 0.13.0
  (#2143)
- Replaced `lazy_static` dependency with `once_cell` (#2147)

### Fixed

- Don't enable `tracing-core` features by default (#2107)
- Several documentation link and typo fixes (#2064, #2068, #2077,
  #2161, #1088)

Thanks to @ben0x539, @jamesmunns, @georgemp, @james7132, @jswrenn,
@CAD97, and @guswynn for contributing to this release!
kaffarell pushed a commit to kaffarell/tracing that referenced this pull request May 22, 2024
* docs: `cargo intraconv` for more intra-doc links

... also it deleted some redundant ones, and it got some things wrong,
and it was gonna delete some of the cross-crate docs.rs links we can't
do as intra-doc links so I passed `--no-favored`.

* docs: convert https:// links to std/core/alloc to intra-doc links

Note that this adds some more broken intra doc links when building
without std support, but that was already a thing and I expect people
who build their own docs without std support can handle it.

This time I gave up on sed and used ruby.

    find -name '*.rs' -exec ruby -i -p blah.rb {} +

with

    $_.gsub!(%r{
        https://doc\.rust-lang\.org/
        (?: stable/)?
        ((?:core | std | alloc)(?:/\S+?)*)
        /(\w+)\.(\w+)\.html}x
    ) {
      path, kind, name = $~.captures
      suffix = case kind
        when 'method' then '()'
        when 'macro' then '!'
        else ''
      end
      r = [path.gsub('/', '::'), '::', name, suffix].join
      STDERR.puts [path, kind, name, suffix, r].inspect
      r
    }
    $_.gsub!(%r{
        https://doc\.rust-lang\.org/
        (?: stable/)?
        ((?: core | std | alloc)(?:/\S+?)*)
        /(?:
          index\.html
          | $
          | (?= \#)
         )}x
    ) {
      path, _ = $~.captures
      r = path.gsub('/', '::')
      STDERR.puts [path, r].inspect
      r
    }

* docs: more cross-crate intra-doc links

cargo intraconv doesn't seem to get them reliably and also plenty of
links to other crates aren't actually intra-doc because they're in
crates that don't depend (or only dev-depend, or only conditionally
depend) on those crates, so this wasn't very automated.

I tried to only convert docs.rs links to unconditional dependencies to
intra-crate links, but it's possible that some slipped through in either
direction.
kaffarell pushed a commit to kaffarell/tracing that referenced this pull request May 22, 2024
# 0.3.0 (April 21, 2022)

This is a breaking release which changes the format in which span fields
are output to `journald`. Previously, span field names were prefixed
with the depth of the span in the current trace tree. However, these
prefixes are unnecessary, as `journald` has built in support for
duplicated field names.

See PR [tokio-rs#1986] for details on this change.

## Changed

- Removed span field prefixes ([tokio-rs#1986])
- Renamed `S{num}_NAME` fields to `SPAN_NAME ([tokio-rs#1986])

### Fixed

- Fixed broken links in documentation ([tokio-rs#2077])

Thanks to @wiktorsikora and @ben0x539 for contributing to this release!

[tokio-rs#1986]: tokio-rs#1986
[tokio-rs#2077]: tokio-rs#2077
kaffarell pushed a commit to kaffarell/tracing that referenced this pull request May 22, 2024
# 0.1.3 (April 21st, 2022)

### Added

- **log-tracer**: Added `LogTracer::with_interest_cache` to enable a
 limited form of per-record `Interest` caching for `log` records
 ([tokio-rs#1636])

### Changed

- Updated minimum supported Rust version (MSRV) to Rust 1.49.0 ([tokio-rs#1913])

### Fixed

- **log-tracer**: Fixed `LogTracer` not honoring `tracing` max level
  filters ([tokio-rs#1543])
- Broken links in documentation ([tokio-rs#2068], [tokio-rs#2077])

Thanks to @Millione, @teozkr, @koute, @Folyd, and @ben0x539 for
contributing to this release!

[tokio-rs#1636]: https://github.com/tokio-rs/tracing/pulls/1636
[tokio-rs#1913]: https://github.com/tokio-rs/tracing/pulls/1913
[tokio-rs#1543]: https://github.com/tokio-rs/tracing/pulls/1543
[tokio-rs#2068]: https://github.com/tokio-rs/tracing/pulls/2068
[tokio-rs#2077]: https://github.com/tokio-rs/tracing/pulls/2077

Fixes tokio-rs#1884
Fixes tokio-rs#1664
kaffarell pushed a commit to kaffarell/tracing that referenced this pull request May 22, 2024
# 0.1.21 (April 26, 2022)

This release adds support for setting explicit parent and follows-from
spans in the `#[instrument]` attribute.

### Added

- `#[instrument(follows_from = ...)]` argument for setting one or more
  follows-from span ([tokio-rs#2093])
- `#[instrument(parent = ...)]` argument for overriding the generated
  span's parent ([tokio-rs#2091])

### Fixed

- Extra braces around `async` blocks in expanded code (causes a Clippy
  warning) ([tokio-rs#2090])
- Broken documentation links ([tokio-rs#2068], [tokio-rs#2077])

Thanks to @jarrodldavis, @ben0x539, and new contributor @jswrenn for
contributing to this release!

[tokio-rs#2093]: tokio-rs#2093
[tokio-rs#2091]: tokio-rs#2091
[tokio-rs#2090]: tokio-rs#2090
[tokio-rs#2077]: tokio-rs#2077
[tokio-rs#2068]: tokio-rs#2068
kaffarell pushed a commit to kaffarell/tracing that referenced this pull request May 22, 2024
# 0.3.12 (Jun 29, 2022)

This release of `tracing-subscriber` adds a new `Layer::event_enabled`
method, which allows `Layer`s to filter events *after* their field
values are recorded; a `Filter` implementation for `reload::Layer`, to
make using `reload` with per-layer filtering more ergonomic, and
additional inherent method downcasting APIs for the `Layered` type. In
addition, it includes dependency updates, and minor fixes for
documentation and feature flagging.

### Added

- **layer**: `Layer::event_enabled` method, which can be implemented to
  filter events based on their field values (tokio-rs#2008)
- **reload**: `Filter` implementation for `reload::Layer` (tokio-rs#2159)
- **layer**: `Layered::downcast_ref` and `Layered::is` inherent methods
  (tokio-rs#2160)

### Changed

- **parking_lot**: Updated dependency on `parking_lot` to 0.13.0
  (tokio-rs#2143)
- Replaced `lazy_static` dependency with `once_cell` (tokio-rs#2147)

### Fixed

- Don't enable `tracing-core` features by default (tokio-rs#2107)
- Several documentation link and typo fixes (tokio-rs#2064, tokio-rs#2068, tokio-rs#2077,
  tokio-rs#2161, tokio-rs#1088)

Thanks to @ben0x539, @jamesmunns, @georgemp, @james7132, @jswrenn,
@CAD97, and @guswynn for contributing to this release!
hds added a commit that referenced this pull request Nov 28, 2024
# 0.2.1 (November 28, 2024)

[ [crates.io][crate-0.2.1] ] | [ [docs.rs][docs-0.2.1] ]

### Changed

- Bump MSRV to 1.63 ([#2793])

### Documented

- Use intra-doc links instead of relative file paths ([#2068])
- More intra-doc links ([#2077])
- Add missing backtick to `prelude` docs ([#2120])

[#2068]: #2068
[#2077]: #2077
[#2120]: #2120
[#2793]: #2793
[docs-0.2.1]: https://docs.rs/tracing-error/0.2.1/tracing_error/
[crate-0.2.1]: https://crates.io/crates/tracing-error/0.2.1
hds added a commit that referenced this pull request Nov 29, 2024
# 0.2.1 (November 29, 2024)

[ [crates.io][crate-0.2.1] ] | [ [docs.rs][docs-0.2.1] ]

### Changed

- Bump MSRV to 1.63 ([#2793])

### Documented

- Use intra-doc links instead of relative file paths ([#2068])
- More intra-doc links ([#2077])
- Add missing backtick to `prelude` docs ([#2120])

[#2068]: #2068
[#2077]: #2077
[#2120]: #2120
[#2793]: #2793
[docs-0.2.1]: https://docs.rs/tracing-error/0.2.1/tracing_error/
[crate-0.2.1]: https://crates.io/crates/tracing-error/0.2.1
hds added a commit that referenced this pull request Nov 29, 2024
# 0.2.1 (November 29, 2024)

[ [crates.io][crate-0.2.1] ] | [ [docs.rs][docs-0.2.1] ]

### Changed

- Bump MSRV to 1.63 ([#2793])

### Documented

- Use intra-doc links instead of relative file paths ([#2068])
- More intra-doc links ([#2077])
- Add missing backtick to `prelude` docs ([#2120])

[#2068]: #2068
[#2077]: #2077
[#2120]: #2120
[#2793]: #2793
[docs-0.2.1]: https://docs.rs/tracing-error/0.2.1/tracing_error/
[crate-0.2.1]: https://crates.io/crates/tracing-error/0.2.1
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants