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

Switch to intra-doc links in tracing-core #1010

Merged
merged 3 commits into from
Oct 2, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
16 changes: 8 additions & 8 deletions tracing-core/src/callsite.rs
Original file line number Diff line number Diff line change
Expand Up @@ -77,20 +77,20 @@ 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
Expand Down Expand Up @@ -119,11 +119,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::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
132 changes: 62 additions & 70 deletions tracing-core/src/dispatcher.rs
Original file line number Diff line number Diff line change
Expand Up @@ -113,11 +113,10 @@
//! </div>
//! <div class="example-wrap" style="display:inline-block">
//! <pre class="ignore" style="white-space:normal;font:inherit;">
//! <strong>Note</strong>:the thread-local scoped dispatcher
//! (<a href="#fn.with_default"><code>with_default</code></a>) requires the
//! Rust standard library. <code>no_std</code> users should use
//! <a href="#fn.set_global_default"><code>set_global_default</code></a>
//! instead.
//!
//! **Note**: the thread-local scoped dispatcher ([`with_default`]) requires the
//! Rust standard library. `no_std` users should use [`set_global_default`] instead.
//!
//! </pre></div>
//!
//! ## Accessing the Default Subscriber
Expand All @@ -126,12 +125,6 @@
//! [`get_default`] function, which executes a closure with a reference to the
//! currently default `Dispatch`. This is used primarily by `tracing`
//! instrumentation.
//!
//! [`Subscriber`]: struct.Subscriber.html
//! [`with_default`]: fn.with_default.html
//! [`set_global_default`]: fn.set_global_default.html
//! [`get_default`]: fn.get_default.html
//! [`Dispatch`]: struct.Dispatch.html
use crate::{
callsite, span,
subscriber::{self, Subscriber},
Expand All @@ -154,8 +147,6 @@ use crate::stdlib::{
};

/// `Dispatch` trace data to a [`Subscriber`].
///
/// [`Subscriber`]: trait.Subscriber.html
#[derive(Clone)]
pub struct Dispatch {
subscriber: Arc<dyn Subscriber + Send + Sync>,
Expand Down Expand Up @@ -217,14 +208,15 @@ pub struct DefaultGuard(Option<Dispatch>);
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: This function required the Rust standard library.
/// <code>no_std</code> users should use <a href="../fn.set_global_default.html">
/// <code>set_global_default</code></a> instead.
/// <!-- hack: this whitespace makes rustdoc interpret the next line as markdown again -->
///
/// `no_std` users should use [`set_global_default`] instead.
///
/// </pre></div>
///
/// [span]: ../span/index.html
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
/// [`Event`]: ../event/struct.Event.html
/// [`set_global_default`]: ../fn.set_global_default.html
/// [span]: super::span
/// [`Subscriber`]: super::subscriber::Subscriber
/// [`Event`]: super::event::Event
#[cfg(feature = "std")]
#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
pub fn with_default<T>(dispatcher: &Dispatch, f: impl FnOnce() -> T) -> T {
Expand All @@ -244,12 +236,11 @@ pub fn with_default<T>(dispatcher: &Dispatch, f: impl FnOnce() -> T) -> T {
/// </div>
/// <div class="example-wrap" style="display:inline-block">
/// <pre class="ignore" style="white-space:normal;font:inherit;">
/// <strong>Note</strong>: This function required the Rust standard library.
/// <code>no_std</code> users should use <a href="../fn.set_global_default.html">
/// <code>set_global_default</code></a> instead.
/// </pre></div>
///
/// [`set_global_default`]: ../fn.set_global_default.html
/// **Note**: This function required the Rust standard library.
/// `no_std` users should use [`set_global_default`] instead.
///
/// </pre></div>
#[cfg(feature = "std")]
#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
#[must_use = "Dropping the guard unregisters the dispatcher."]
Expand All @@ -276,9 +267,9 @@ pub fn set_default(dispatcher: &Dispatch) -> DefaultGuard {
/// executables that depend on the library try to set the default later.
/// </pre></div>
///
/// [span]: ../span/index.html
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
/// [`Event`]: ../event/struct.Event.html
/// [span]: super::span
/// [`Subscriber`]: super::subscriber::Subscriber
/// [`Event`]: super::event::Event
pub fn set_global_default(dispatcher: Dispatch) -> Result<(), SetGlobalDefaultError> {
if GLOBAL_INIT.compare_and_swap(UNINITIALIZED, INITIALIZING, Ordering::SeqCst) == UNINITIALIZED
{
Expand Down Expand Up @@ -325,7 +316,7 @@ impl error::Error for SetGlobalDefaultError {}
/// called while inside of another `get_default`, that closure will be provided
/// with `Dispatch::none` rather than the previously set dispatcher.
///
/// [dispatcher]: ../dispatcher/struct.Dispatch.html
/// [dispatcher]: super::dispatcher::Dispatch
#[cfg(feature = "std")]
pub fn get_default<T, F>(mut f: F) -> T
where
Expand All @@ -348,7 +339,7 @@ where
/// called while inside of another `get_default`, that closure will be provided
/// with `Dispatch::none` rather than the previously set dispatcher.
///
/// [dispatcher]: ../dispatcher/struct.Dispatch.html
/// [dispatcher]: super::dispatcher::Dispatch
#[cfg(feature = "std")]
#[doc(hidden)]
#[inline(never)]
Expand All @@ -363,7 +354,7 @@ pub fn get_current<T>(f: impl FnOnce(&Dispatch) -> T) -> Option<T> {

/// Executes a closure with a reference to the current [dispatcher].
///
/// [dispatcher]: ../dispatcher/struct.Dispatch.html
/// [dispatcher]: super::dispatcher::Dispatch
#[cfg(not(feature = "std"))]
#[doc(hidden)]
pub fn get_current<T>(f: impl FnOnce(&Dispatch) -> T) -> Option<T> {
Expand All @@ -373,7 +364,7 @@ pub fn get_current<T>(f: impl FnOnce(&Dispatch) -> T) -> Option<T> {

/// Executes a closure with a reference to the current [dispatcher].
///
/// [dispatcher]: ../dispatcher/struct.Dispatch.html
/// [dispatcher]: super::dispatcher::Dispatch
#[cfg(not(feature = "std"))]
pub fn get_default<T, F>(mut f: F) -> T
where
Expand Down Expand Up @@ -412,7 +403,7 @@ impl Dispatch {

/// Returns a `Dispatch` that forwards to the given [`Subscriber`].
///
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
/// [`Subscriber`]: super::subscriber::Subscriber
pub fn new<S>(subscriber: S) -> Self
where
S: Subscriber + Send + Sync + 'static,
Expand All @@ -434,8 +425,8 @@ impl Dispatch {
/// This calls the [`register_callsite`] function on the [`Subscriber`]
/// that this `Dispatch` forwards to.
///
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
/// [`register_callsite`]: ../subscriber/trait.Subscriber.html#method.register_callsite
/// [`Subscriber`]: super::subscriber::Subscriber
/// [`register_callsite`]: super::subscriber::Subscriber::register_callsite
#[inline]
pub fn register_callsite(&self, metadata: &'static Metadata<'static>) -> subscriber::Interest {
self.subscriber.register_callsite(metadata)
Expand All @@ -448,9 +439,9 @@ impl Dispatch {
/// This calls the [`max_level_hint`] function on the [`Subscriber`]
/// that this `Dispatch` forwards to.
///
/// [level]: ../struct.Level.html
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
/// [`register_callsite`]: ../subscriber/trait.Subscriber.html#method.max_level_hint
/// [level]: super::Level
/// [`Subscriber`]: super::subscriber::Subscriber
/// [`register_callsite`]: super::subscriber::Subscriber::max_level_hint
// TODO(eliza): consider making this a public API?
#[inline]
pub(crate) fn max_level_hint(&self) -> Option<LevelFilter> {
Expand All @@ -463,9 +454,9 @@ impl Dispatch {
/// This calls the [`new_span`] function on the [`Subscriber`] that this
/// `Dispatch` forwards to.
///
/// [ID]: ../span/struct.Id.html
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
/// [`new_span`]: ../subscriber/trait.Subscriber.html#method.new_span
/// [ID]: super::span::Id
/// [`Subscriber`]: super::subscriber::Subscriber
/// [`new_span`]: super::subscriber::Subscriber::new_span
#[inline]
pub fn new_span(&self, span: &span::Attributes<'_>) -> span::Id {
self.subscriber.new_span(span)
Expand All @@ -476,8 +467,8 @@ impl Dispatch {
/// This calls the [`record`] function on the [`Subscriber`] that this
/// `Dispatch` forwards to.
///
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
/// [`record`]: ../subscriber/trait.Subscriber.html#method.record
/// [`Subscriber`]: super::subscriber::Subscriber
/// [`record`]: super::subscriber::Subscriber::record
#[inline]
pub fn record(&self, span: &span::Id, values: &span::Record<'_>) {
self.subscriber.record(span, values)
Expand All @@ -489,8 +480,8 @@ impl Dispatch {
/// This calls the [`record_follows_from`] function on the [`Subscriber`]
/// that this `Dispatch` forwards to.
///
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
/// [`record_follows_from`]: ../subscriber/trait.Subscriber.html#method.record_follows_from
/// [`Subscriber`]: super::subscriber::Subscriber
/// [`record_follows_from`]: super::subscriber::Subscriber::record_follows_from
#[inline]
pub fn record_follows_from(&self, span: &span::Id, follows: &span::Id) {
self.subscriber.record_follows_from(span, follows)
Expand All @@ -502,9 +493,9 @@ impl Dispatch {
/// This calls the [`enabled`] function on the [`Subscriber`] that this
/// `Dispatch` forwards to.
///
/// [metadata]: ../metadata/struct.Metadata.html
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
/// [`enabled`]: ../subscriber/trait.Subscriber.html#method.enabled
/// [metadata]: super::metadata::Metadata
/// [`Subscriber`]: super::subscriber::Subscriber
/// [`enabled`]: super::subscriber::Subscriber::enabled
#[inline]
pub fn enabled(&self, metadata: &Metadata<'_>) -> bool {
self.subscriber.enabled(metadata)
Expand All @@ -515,9 +506,9 @@ impl Dispatch {
/// This calls the [`event`] function on the [`Subscriber`] that this
/// `Dispatch` forwards to.
///
/// [`Event`]: ../event/struct.Event.html
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
/// [`event`]: ../subscriber/trait.Subscriber.html#method.event
/// [`Event`]: super::event::Event
/// [`Subscriber`]: super::subscriber::Subscriber
/// [`event`]: super::subscriber::Subscriber::event
#[inline]
pub fn event(&self, event: &Event<'_>) {
self.subscriber.event(event)
Expand All @@ -528,8 +519,8 @@ impl Dispatch {
/// This calls the [`enter`] function on the [`Subscriber`] that this
/// `Dispatch` forwards to.
///
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
/// [`enter`]: ../subscriber/trait.Subscriber.html#method.enter
/// [`Subscriber`]: super::subscriber::Subscriber
/// [`enter`]: super::subscriber::Subscriber::enter
#[inline]
pub fn enter(&self, span: &span::Id) {
self.subscriber.enter(span);
Expand All @@ -540,8 +531,8 @@ impl Dispatch {
/// This calls the [`exit`] function on the [`Subscriber`] that this
/// `Dispatch` forwards to.
///
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
/// [`exit`]: ../subscriber/trait.Subscriber.html#method.exit
/// [`Subscriber`]: super::subscriber::Subscriber
/// [`exit`]: super::subscriber::Subscriber::exit
#[inline]
pub fn exit(&self, span: &span::Id) {
self.subscriber.exit(span);
Expand All @@ -557,10 +548,10 @@ impl Dispatch {
/// This calls the [`clone_span`] function on the `Subscriber` that this
/// `Dispatch` forwards to.
///
/// [span ID]: ../span/struct.Id.html
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
/// [`clone_span`]: ../subscriber/trait.Subscriber.html#method.clone_span
/// [`new_span`]: ../subscriber/trait.Subscriber.html#method.new_span
/// [span ID]: super::span::Id
/// [`Subscriber`]: super::subscriber::Subscriber
/// [`clone_span`]: super::subscriber::Subscriber::clone_span
/// [`new_span`]: super::subscriber::Subscriber::new_span
#[inline]
pub fn clone_span(&self, id: &span::Id) -> span::Id {
self.subscriber.clone_span(&id)
Expand All @@ -580,16 +571,17 @@ impl Dispatch {
/// <div class="tooltip compile_fail" style="">&#x26a0; &#xfe0f;<span class="tooltiptext">Warning</span></div>
/// </div>
/// <div class="example-wrap" style="display:inline-block"><pre class="compile_fail" style="white-space:normal;font:inherit;">
/// <strong>Deprecated</strong>: The <a href="#method.try_close"><code>try_close</code></a>
/// method is functionally identical, but returns <code>true</code> if the span is now closed.
///
/// **Deprecated**: The [`try_close`] method is functionally identical, but returns `true` if the span is now closed.
/// It should be used instead of this method.
///
/// </pre></div>
///
/// [span ID]: ../span/struct.Id.html
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
/// [`drop_span`]: ../subscriber/trait.Subscriber.html#method.drop_span
/// [`new_span`]: ../subscriber/trait.Subscriber.html#method.new_span
/// [`try_close`]: #method.try_close
/// [span ID]: super::span::Id
/// [`Subscriber`]: super::subscriber::Subscriber
/// [`drop_span`]: super::subscriber::Subscriber::drop_span
/// [`new_span`]: super::subscriber::Subscriber::new_span
/// [`try_close`]: Self::try_close
#[inline]
#[deprecated(since = "0.1.2", note = "use `Dispatch::try_close` instead")]
pub fn drop_span(&self, id: span::Id) {
Expand All @@ -608,10 +600,10 @@ impl Dispatch {
/// This calls the [`try_close`] function on the [`Subscriber`] that this
/// `Dispatch` forwards to.
///
/// [span ID]: ../span/struct.Id.html
/// [`Subscriber`]: ../subscriber/trait.Subscriber.html
/// [`try_close`]: ../subscriber/trait.Subscriber.html#method.try_close
/// [`new_span`]: ../subscriber/trait.Subscriber.html#method.new_span
/// [span ID]: super::span::Id
/// [`Subscriber`]: super::subscriber::Subscriber
/// [`try_close`]: super::subscriber::Subscriber::try_close
/// [`new_span`]: super::subscriber::Subscriber::new_span
#[inline]
pub fn try_close(&self, id: span::Id) -> bool {
self.subscriber.try_close(id)
Expand All @@ -622,7 +614,7 @@ impl Dispatch {
/// This calls the [`current`] function on the `Subscriber` that this
/// `Dispatch` forwards to.
///
/// [`current`]: ../subscriber/trait.Subscriber.html#method.current
/// [`current`]: super::subscriber::Subscriber::current_span
#[inline]
pub fn current_span(&self) -> span::Current {
self.subscriber.current_span()
Expand Down
4 changes: 2 additions & 2 deletions tracing-core/src/event.rs
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ impl<'a> Event<'a> {

/// Visits all the fields on this `Event` with the specified [visitor].
///
/// [visitor]: ../field/trait.Visit.html
/// [visitor]: super::field::Visit
#[inline]
pub fn record(&self, visitor: &mut dyn field::Visit) {
self.fields.record(visitor);
Expand All @@ -94,7 +94,7 @@ impl<'a> Event<'a> {

/// Returns [metadata] describing this `Event`.
///
/// [metadata]: ../struct.Metadata.html
/// [metadata]: super::Metadata
pub fn metadata(&self) -> &'static Metadata<'static> {
self.metadata
}
Expand Down
Loading