Skip to content

Commit

Permalink
docs: switch to intra-doc links in tracing-core (#1010)
Browse files Browse the repository at this point in the history 
## Motivation

This caught multiple broken links in the documentation. Partially
addresses #940.

## Solution

Use intra-doc links so rustdoc will give a loud warning if the
documentation has errors.

Most of these were auto-converted with

```
rg -l '\[.*\]: .*(trait|struct|enum|fn)\..*\.html*' | grep '\.rs$' | xargs sed -i 's#\.\./\(.*\.html\)#super::\1#g; s#\([a-z]\)/\([a-z]\)#\1::\2#g; s#[a-z]\+\.\([a-zA-Z]\+\)\.html#\1#; s/\([a-z]\)#\(ty\)\?method./\1::/; s/#\(ty\)\?method./Self::/'
```

The rest were massaged by hand. In particular
`<dyn Subscriber>::downcast_ref` isn't yet supported by rustdoc and
can't be converted.
  • Loading branch information
@jyn514
jyn514 authored Oct 2, 2020
1 parent 04bbb15 commit e8d2567
Show file tree
Hide file tree
Showing 8 changed files with 185 additions and 198 deletions.
16 changes: 8 additions & 8 deletions tracing-core/src/callsite.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,20 +38,20 @@ struct 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 @@ -92,11 +92,11 @@ pub struct Registration<T = &'static dyn Callsite> {
/// 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 dispatchers = REGISTRY.dispatchers.lock().unwrap();
let callsites = &REGISTRY.callsites;
Expand Down
132 changes: 62 additions & 70 deletions tracing-core/src/dispatcher.rs
View file
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
View file
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

0 comments on commit e8d2567

Please sign in to comment.