Skip to content

Commit

Permalink
docs: use intra-doc links instead of relative file paths (#2068)
Browse files Browse the repository at this point in the history
## Motivation

#940, I guess. I kept running into the odd broken link in the docs and
eventually realized it's because a lot of stuff is reexported in parent
modules and so the file path based relative links couldn't possibly work
in all contexts. Looks like master already underwent this treatment but
I suspect this is easier than backporting.

## Solution

Intra-doc links seem pretty good.

I started with

```
        find -name \*.rs -exec sed -i -e '
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\w\+\.\(\w\+\)\.html@\1super::\2@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\(\w\+\)/\w\+\.\(\w\+\)\.html@\1super::\2::\3@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\.\./\w\+\.\(\w\+\)\.html@\1super::super::\2@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\.\./\(\w\+\)/\w\+\.\(\w\+\)\.html@\1super::super::\2::\3@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\(\w\+\)/index\.html@\1super::\2@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./index\.html@\1super@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\(\w\+\)/\?$@\1super::\2@;
    
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\w\+\.\(\w\+\)\.html@\1self::\2@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\(\w\+\)/\w\+\.\(\w\+\)\.html@\1self::\2::\3@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\(\w\+\)/index\.html@\1self::\2@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./index\.html@\1self@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\(\w\+\)/\?$@\1self::\2@;
    
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\w\+\.\(\w\+\)\.html@\1self::\2@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\(\w\+\)/\w\+\.\(\w\+\)\.html@\1self::\2::\3@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\(\w\+\)/index\.html@\1self::\2@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?index\.html@\1self@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\(\w\+\)/\?$@\1self::\2@;
    
            s@\(//. \[[^]]*\]:\s\+[A-Za-z_0-9:]\+\)#method\.\(\w\+\)@\1::\2@;
        ' {} +
```
and then removed redundant `self::`s when I realized you don't actually
need a `::` in the links, and fixed stuff up by hand as I ran into
errors from

```
x='--cfg docsrs --cfg tracing_unstable'; RUSTFLAGS=$x RUSTDOCFLAGS=$x cargo doc --all-features
```

I hope that's roughly how the docs are supposed to work.

I understand this is a relatively big unsolicited change in that it
touches a whole lot of files (definitely went further than I originally
intended), I'm happy to revise or split or reduce scope of this PR as
desired.
  • Loading branch information
ben0x539 authored Apr 14, 2022
1 parent 9d10e2c commit 438b013
Show file tree
Hide file tree
Showing 40 changed files with 386 additions and 390 deletions.
12 changes: 6 additions & 6 deletions tracing-appender/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
//! *Compiler support: [requires `rustc` 1.53+][msrv]*
//!
//! [msrv]: #supported-rust-versions
//! [file_appender]: ./rolling/struct.RollingFileAppender.html
//! [file_appender]: rolling::RollingFileAppender
//! [tracing]: https://docs.rs/tracing/
//!
//! # Usage
Expand Down Expand Up @@ -88,12 +88,12 @@
//!
//! The [`non_blocking` module][non_blocking]'s documentation provides more detail on how to use `non_blocking`.
//!
//! [non_blocking]: ./non_blocking/index.html
//! [non_blocking]: mod@non_blocking
//! [write]: https://doc.rust-lang.org/std/io/trait.Write.html
//! [guard]: ./non_blocking/struct.WorkerGuard.html
//! [rolling]: ./rolling/index.html
//! [guard]: non_blocking::WorkerGuard
//! [rolling]: rolling
//! [make_writer]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/trait.MakeWriter.html
//! [rolling_struct]: ./rolling/struct.RollingFileAppender.html
//! [rolling_struct]: rolling::RollingFileAppender
//! [fmt_subscriber]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.Subscriber.html
//!
//! ## Non-Blocking Rolling File Appender
Expand Down Expand Up @@ -166,7 +166,7 @@ pub(crate) mod sync;
///
/// See the [`non_blocking` module's docs][non_blocking]'s for more details.
///
/// [non_blocking]: ./non_blocking/index.html
/// [non_blocking]: mod@non_blocking
///
/// # Examples
///
Expand Down
14 changes: 7 additions & 7 deletions tracing-appender/src/non_blocking.rs
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
//! tracing_appender::non_blocking(std::io::stdout())
//! # }
//! ```
//! [builder]: ./struct.NonBlockingBuilder.html#method.default
//! [builder]: NonBlockingBuilder::default
//!
//! <br/> This function returns a tuple of `NonBlocking` and `WorkerGuard`.
//! `NonBlocking` implements [`MakeWriter`] which integrates with `tracing_subscriber`.
Expand All @@ -33,7 +33,7 @@
//!
//! See [`WorkerGuard`][worker_guard] for examples of using the guard.
//!
//! [worker_guard]: ./struct.WorkerGuard.html
//! [worker_guard]: WorkerGuard
//!
//! # Examples
//!
Expand Down Expand Up @@ -65,7 +65,7 @@ use tracing_subscriber::fmt::MakeWriter;
/// backpressure will be exerted on senders, causing them to block their
/// respective threads until there is available capacity.
///
/// [non-blocking]: ./struct.NonBlocking.html
/// [non-blocking]: NonBlocking
/// Recommended to be a power of 2.
pub const DEFAULT_BUFFERED_LINES_LIMIT: usize = 128_000;

Expand All @@ -78,7 +78,7 @@ pub const DEFAULT_BUFFERED_LINES_LIMIT: usize = 128_000;
/// terminates abruptly (such as through an uncaught `panic` or a `std::process::exit`), some spans
/// or events may not be written.
///
/// [`NonBlocking`]: ./struct.NonBlocking.html
/// [`NonBlocking`]: NonBlocking
/// Since spans/events and events recorded near a crash are often necessary for diagnosing the failure,
/// `WorkerGuard` provides a mechanism to ensure that _all_ buffered logs are flushed to their output.
/// `WorkerGuard` should be assigned in the `main` function or whatever the entrypoint of the program is.
Expand Down Expand Up @@ -145,8 +145,8 @@ impl NonBlocking {
/// The returned `NonBlocking` writer will have the [default configuration][default] values.
/// Other configurations can be specified using the [builder] interface.
///
/// [default]: ./struct.NonBlockingBuilder.html#method.default
/// [builder]: ./struct.NonBlockingBuilder.html
/// [default]: NonBlockingBuilder::default
/// [builder]: NonBlockingBuilder
pub fn new<T: Write + Send + Sync + 'static>(writer: T) -> (NonBlocking, WorkerGuard) {
NonBlockingBuilder::default().finish(writer)
}
Expand Down Expand Up @@ -183,7 +183,7 @@ impl NonBlocking {

/// A builder for [`NonBlocking`][non-blocking].
///
/// [non-blocking]: ./struct.NonBlocking.html
/// [non-blocking]: NonBlocking
#[derive(Debug)]
pub struct NonBlockingBuilder {
buffered_lines_limit: usize,
Expand Down
22 changes: 11 additions & 11 deletions tracing-appender/src/rolling.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
//! A rolling file appender.
//!
//! Creates a new log file at a fixed frequency as defined by [`Rotation`](struct.Rotation.html).
//! Creates a new log file at a fixed frequency as defined by [`Rotation`][self::Rotation].
//! Logs will be written to this file for the duration of the period and will automatically roll over
//! to the newly created log file once the time period has elapsed.
//!
Expand All @@ -17,10 +17,10 @@
//! will be created daily
//! - [`Rotation::never()`][never()]: This will result in log file located at `some_directory/log_file_name`
//!
//! [minutely]: fn.minutely.html
//! [hourly]: fn.hourly.html
//! [daily]: fn.daily.html
//! [never]: fn.never.html
//! [minutely]: minutely
//! [hourly]: hourly
//! [daily]: daily
//! [never]: never
//!
//! # Examples
//!
Expand Down Expand Up @@ -114,7 +114,7 @@ impl RollingFileAppender {
/// Creates a new `RollingFileAppender`.
///
/// A `RollingFileAppender` will have a fixed rotation whose frequency is
/// defined by [`Rotation`](struct.Rotation.html). The `directory` and
/// defined by [`Rotation`][self::Rotation]. The `directory` and
/// `file_name_prefix` arguments determine the location and file name's _prefix_
/// of the log file. `RollingFileAppender` will automatically append the current date
/// and hour (UTC format) to the file name.
Expand All @@ -126,10 +126,10 @@ impl RollingFileAppender {
/// - [`Rotation::daily()`][daily],
/// - [`Rotation::never()`][never()]
///
/// [minutely]: fn.minutely.html
/// [hourly]: fn.hourly.html
/// [daily]: fn.daily.html
/// [never]: fn.never.html
/// [minutely]: minutely
/// [hourly]: hourly
/// [daily]: daily
/// [never]: never
///
/// # Examples
/// ```rust
Expand Down Expand Up @@ -284,7 +284,7 @@ pub fn hourly(
/// a non-blocking, daily file appender.
///
/// A `RollingFileAppender` has a fixed rotation whose frequency is
/// defined by [`Rotation`](struct.Rotation.html). The `directory` and
/// defined by [`Rotation`][self::Rotation]. The `directory` and
/// `file_name_prefix` arguments determine the location and file name's _prefix_
/// of the log file. `RollingFileAppender` automatically appends the current date in UTC.
///
Expand Down
2 changes: 1 addition & 1 deletion tracing-attributes/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@
//!
//! [`tracing`]: https://crates.io/crates/tracing
//! [span]: https://docs.rs/tracing/latest/tracing/span/index.html
//! [instrument]: attr.instrument.html
//! [instrument]: macro@self::instrument
//!
//! ## Supported Rust Versions
//!
Expand Down
21 changes: 10 additions & 11 deletions tracing-core/src/callsite.rs
Original file line number Diff line number Diff line change
Expand Up @@ -77,30 +77,29 @@ impl Registry {
pub trait Callsite: Sync {
/// Sets the [`Interest`] for this callsite.
///
/// [`Interest`]: ../subscriber/struct.Interest.html
/// [`Interest`]: super::subscriber::Interest
fn set_interest(&self, interest: Interest);

/// Returns the [metadata] associated with the callsite.
///
/// [metadata]: ../metadata/struct.Metadata.html
/// [metadata]: super::metadata::Metadata
fn metadata(&self) -> &Metadata<'_>;
}

/// Uniquely identifies a [`Callsite`]
///
/// Two `Identifier`s are equal if they both refer to the same callsite.
///
/// [`Callsite`]: ../callsite/trait.Callsite.html
/// [`Callsite`]: super::callsite::Callsite
#[derive(Clone)]
pub struct Identifier(
/// **Warning**: The fields on this type are currently `pub` because it must
/// be able to be constructed statically by macros. However, when `const
/// fn`s are available on stable Rust, this will no longer be necessary.
/// Thus, these fields are *not* considered stable public API, and they may
/// change warning. Do not rely on any fields on `Identifier`. When
/// constructing new `Identifier`s, use the `identify_callsite!` macro or
/// the `Callsite::id` function instead.
// TODO: When `Callsite::id` is a const fn, this need no longer be `pub`.
/// constructing new `Identifier`s, use the `identify_callsite!` macro
/// instead.
#[doc(hidden)]
pub &'static dyn Callsite,
);
Expand All @@ -119,11 +118,11 @@ pub struct Identifier(
/// 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
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
/// [`max_level_hint`]: super::subscriber::Subscriber::max_level_hint
/// [`Callsite`]: super::callsite::Callsite
/// [`enabled`]: super::subscriber::Subscriber#tymethod.enabled
/// [`Interest::sometimes()`]: super::subscriber::Interest::sometimes
/// [`Subscriber`]: super::subscriber::Subscriber
pub fn rebuild_interest_cache() {
let mut registry = REGISTRY.lock().unwrap();
registry.rebuild_interest();
Expand Down
Loading

0 comments on commit 438b013

Please sign in to comment.