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.

Sign up for GitHub

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

Jump to bottom

intra doc links instead of relative file paths #2068

Merged
merged 6 commits into from
Apr 14, 2022
Merged

intra doc links instead of relative file paths #2068

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
71e7052
docs: sed relative links into intra-doc links
ben0x539 Apr 12, 2022
ddacda1
docs: fix/remove now-detected-as-broken intra doc links
ben0x539 Apr 12, 2022
c34dddb
docs: remove redundant self::
ben0x539 Apr 12, 2022
d07500a
docs: also replace relative [...](...) with intra-doc links
ben0x539 Apr 12, 2022
b7bba06
docs: catch line-broken [blah]: ../blah style links
ben0x539 Apr 12, 2022
b544354
Merge branch 'v0.1.x' into v0.1.x-intra-doc-links
hawkw Apr 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions tracing-appender/src/lib.rs
View file
Open in desktop
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
Copy link
Member

Choose a reason for hiding this comment

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

can we also apply this treatment to docs links to the standard library? it would be fine to do that in a separate PR, though.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

definitely (tho prefer separate pr), i'm gonna read up more on how those links work for cross crate references :v

//! [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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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