docs: more intra-doc links (tokio-rs#2077)

* 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 · May 22, 2024 · 7464f40 · 7464f40
1 parent 62dd708
commit 7464f40
Show file tree

Hide file tree

Showing 13 changed files with 76 additions and 99 deletions.
diff --git a/tracing-core/src/dispatcher.rs b/tracing-core/src/dispatcher.rs
@@ -123,11 +123,6 @@
 //! currently default `Dispatch`. This is used primarily by `tracing`
 //! instrumentation.
 //!
-//! [`Subscriber`]: Subscriber
-//! [`with_default`]: with_default
-//! [`set_global_default`]: set_global_default
-//! [`get_default`]: get_default
-//! [`Dispatch`]: Dispatch
 use crate::{
     callsite, span,
     subscriber::{self, NoSubscriber, Subscriber},
@@ -151,7 +146,6 @@ use crate::stdlib::{
 
 /// `Dispatch` trace data to a [`Subscriber`].
 ///
-/// [`Subscriber`]: Subscriber
 #[derive(Clone)]
 pub struct Dispatch {
     subscriber: Arc<dyn Subscriber + Send + Sync>,
@@ -579,7 +573,7 @@ impl Dispatch {
     /// [`Subscriber`]: super::subscriber::Subscriber
     /// [`drop_span`]: super::subscriber::Subscriber::drop_span
     /// [`new_span`]: super::subscriber::Subscriber::new_span
-    /// [`try_close`]: #method.try_close
+    /// [`try_close`]: Entered::try_close()
     #[inline]
     #[deprecated(since = "0.1.2", note = "use `Dispatch::try_close` instead")]
     pub fn drop_span(&self, id: span::Id) {

diff --git a/tracing-core/src/subscriber.rs b/tracing-core/src/subscriber.rs
@@ -67,7 +67,6 @@ use crate::stdlib::{
 /// [ID]: super::span::Id
 /// [`new_span`]: Subscriber::new_span
 /// [`register_callsite`]: Subscriber::register_callsite
-/// [`Interest`]: Interest
 /// [`enabled`]: Subscriber::enabled
 /// [`clone_span`]: Subscriber::clone_span
 /// [`try_close`]: Subscriber::try_close
@@ -136,10 +135,9 @@ pub trait Subscriber: 'static {
     /// _may_ still see spans and events originating from that callsite, if
     /// another subscriber expressed interest in it.
     ///
-    /// [filter]: #method.enabled
+    /// [filter]: Subscriber::enabled()
     /// [metadata]: super::metadata::Metadata
-    /// [`Interest`]: Interest
-    /// [`enabled`]: #method.enabled
+    /// [`enabled`]: Subscriber::enabled()
     /// [`rebuild_interest_cache`]: super::callsite::rebuild_interest_cache
     fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest {
         if self.enabled(metadata) {
@@ -168,7 +166,7 @@ pub trait Subscriber: 'static {
     /// [metadata]: super::metadata::Metadata
     /// [interested]: Interest
     /// [`Interest::sometimes`]: Interest::sometimes
-    /// [`register_callsite`]: #method.register_callsite
+    /// [`register_callsite`]: Subscriber::register_callsite()
     fn enabled(&self, metadata: &Metadata<'_>) -> bool;
 
     /// Returns the highest [verbosity level][level] that this `Subscriber` will
@@ -192,7 +190,6 @@ pub trait Subscriber: 'static {
     /// level changes.
     ///
     /// [level]: super::Level
-    /// [`Interest`]: Interest
     /// [rebuild]: super::callsite::rebuild_interest_cache
     fn max_level_hint(&self) -> Option<LevelFilter> {
         None

diff --git a/tracing-log/src/lib.rs b/tracing-log/src/lib.rs
@@ -92,7 +92,6 @@
 //! [`init`]: LogTracer::init()
 //! [`init_with_filter`]: LogTracer::init_with_filter()
 //! [`tracing`]: https://crates.io/crates/tracing
-//! [`log`]: https://crates.io/crates/log
 //! [`env_logger` crate]: https://crates.io/crates/env-logger
 //! [`tracing::Collector`]: tracing::Collect
 //! [`tracing::Event`]: tracing_core::Event

diff --git a/tracing-log/src/trace_logger.rs b/tracing-log/src/trace_logger.rs
@@ -8,10 +8,9 @@
 //! `tracing` events as `log` records, the ["log" and "log-always" feature
 //! flags][flags] on the `tracing` crate should be used instead.
 //!
-//! [`log`]: https://docs.rs/log/0.4.8/log/index.html
+//! [`log`]: log
 //! [`Subscriber`]: https://docs.rs/tracing/0.1.7/tracing/subscriber/trait.Subscriber.html
-//! [`TraceLogger`]: TraceLogger
-//! [`log::Record`]: https://docs.rs/log/0.4.8/log/struct.Record.html
+//! [`log::Record`]:log::Record
 //! [flags]: https://docs.rs/tracing/latest/tracing/#crate-feature-flags
 #![deprecated(
     since = "0.1.1",
@@ -53,7 +52,6 @@ thread_local! {
 }
 /// Configures and constructs a [`TraceLogger`].
 ///
-/// [`TraceLogger`]: TraceLogger
 #[derive(Debug)]
 pub struct Builder {
     log_span_closes: bool,
@@ -95,7 +93,6 @@ impl Builder {
     /// Configures whether or not the [`TraceLogger`] being constructed will log
     /// when a span closes.
     ///
-    /// [`TraceLogger`]: TraceLogger
     pub fn with_span_closes(self, log_span_closes: bool) -> Self {
         Self {
             log_span_closes,
@@ -106,7 +103,6 @@ impl Builder {
     /// Configures whether or not the [`TraceLogger`] being constructed will
     /// include the fields of parent spans when formatting events.
     ///
-    /// [`TraceLogger`]: TraceLogger
     pub fn with_parent_fields(self, parent_fields: bool) -> Self {
         Self {
             parent_fields,
@@ -120,38 +116,33 @@ impl Builder {
     /// If this is set to false, fields from the current span will still be
     /// recorded as context, but the actual entry will not create a log record.
     ///
-    /// [`TraceLogger`]: TraceLogger
     pub fn with_span_entry(self, log_enters: bool) -> Self {
         Self { log_enters, ..self }
     }
 
     /// Configures whether or not the [`TraceLogger`] being constructed will log
     /// when a span is exited.
     ///
-    /// [`TraceLogger`]: TraceLogger
     pub fn with_span_exits(self, log_exits: bool) -> Self {
         Self { log_exits, ..self }
     }
 
     /// Configures whether or not the [`TraceLogger`] being constructed will
     /// include span IDs when formatting log output.
     ///
-    /// [`TraceLogger`]: TraceLogger
     pub fn with_ids(self, log_ids: bool) -> Self {
         Self { log_ids, ..self }
     }
 
     /// Configures whether or not the [`TraceLogger`] being constructed will
     /// include the names of parent spans as context when formatting events.
     ///
-    /// [`TraceLogger`]: TraceLogger
     pub fn with_parent_names(self, log_parent: bool) -> Self {
         Self { log_parent, ..self }
     }
 
     /// Complete the builder, returning a configured [`TraceLogger`].
     ///
-    /// [`TraceLogger`]: TraceLogger
     pub fn finish(self) -> TraceLogger {
         TraceLogger::from_builder(self)
     }

diff --git a/tracing-opentelemetry/src/lib.rs b/tracing-opentelemetry/src/lib.rs
@@ -26,8 +26,8 @@
 //! * `otel.status_code`: Set the span status code to one of the supported OpenTelemetry [span status codes].
 //! * `otel.status_message`: Set the span status message.
 //!
-//! [span kinds]: https://docs.rs/opentelemetry/latest/opentelemetry/trace/enum.SpanKind.html
-//! [span status codes]: https://docs.rs/opentelemetry/latest/opentelemetry/trace/enum.StatusCode.html
+//! [span kinds]: opentelemetry::trace::SpanKind
+//! [span status codes]: opentelemetry::trace::StatusCode
 //!
 //! ### Semantic Conventions
 //!

diff --git a/tracing-opentelemetry/src/span_ext.rs b/tracing-opentelemetry/src/span_ext.rs
@@ -4,7 +4,7 @@ use opentelemetry::{trace::SpanContext, Context, KeyValue};
 /// Utility functions to allow tracing [`Span`]s to accept and return
 /// [OpenTelemetry] [`Context`]s.
 ///
-/// [`Span`]: https://docs.rs/tracing/latest/tracing/struct.Span.html
+/// [`Span`]: tracing::Span
 /// [OpenTelemetry]: https://opentelemetry.io
 /// [`Context`]: opentelemetry::Context
 pub trait OpenTelemetrySpanExt {

diff --git a/tracing-subscriber/src/fmt/fmt_layer.rs b/tracing-subscriber/src/fmt/fmt_layer.rs
@@ -393,7 +393,7 @@ where
     /// `Layer`s added to this subscriber.
     ///
     /// [lifecycle]: https://docs.rs/tracing/latest/tracing/span/index.html#the-span-lifecycle
-    /// [time]: #method.without_time
+    /// [time]: Layer::without_time()
     pub fn with_span_events(self, kind: FmtSpan) -> Self {
         Layer {
             fmt_span: self.fmt_span.with_kind(kind),
@@ -444,7 +444,7 @@ where
     /// Sets whether or not the [thread ID] of the current thread is displayed
     /// when formatting events
     ///
-    /// [thread ID]: https://doc.rust-lang.org/stable/std/thread/struct.ThreadId.html
+    /// [thread ID]: std::thread::ThreadId
     pub fn with_thread_ids(self, display_thread_ids: bool) -> Layer<S, N, format::Format<L, T>, W> {
         Layer {
             fmt_event: self.fmt_event.with_thread_ids(display_thread_ids),
@@ -455,7 +455,7 @@ where
     /// Sets whether or not the [name] of the current thread is displayed
     /// when formatting events
     ///
-    /// [name]: https://doc.rust-lang.org/stable/std/thread/index.html#naming-threads
+    /// [name]: std::thread#naming-threads
     pub fn with_thread_names(
         self,
         display_thread_names: bool,
@@ -510,7 +510,7 @@ where
     /// - [`Layer::flatten_event`] can be used to enable flattening event fields into the root
     /// object.
     ///
-    /// [`Layer::flatten_event`]: #method.flatten_event
+    /// [`Layer::flatten_event`]: Layer::flatten_event()
     #[cfg(feature = "json")]
     #[cfg_attr(docsrs, doc(cfg(feature = "json")))]
     pub fn json(self) -> Layer<S, format::JsonFields, format::Format<format::Json, T>, W> {

diff --git a/tracing-subscriber/src/fmt/time/time_crate.rs b/tracing-subscriber/src/fmt/time/time_crate.rs
@@ -19,10 +19,10 @@ use time::{format_description::well_known, formatting::Formattable, OffsetDateTi
 ///    documentation</a> for more details.
 /// </pre></div>
 ///
-/// [local time]: https://docs.rs/time/0.3/time/struct.OffsetDateTime.html#method.now_local
-/// [UTC time]: https://docs.rs/time/0.3/time/struct.OffsetDateTime.html#method.now_utc
-/// [formatter]: https://docs.rs/time/0.3/time/formatting/trait.Formattable.html
-/// [`time` crate]: https://docs.rs/time/0.3/time/
+/// [local time]: time::OffsetDateTime::now_local
+/// [UTC time]:     time::OffsetDateTime::now_utc
+/// [formatter]:    time::formatting::Formattable
+/// [`time` crate]: time
 #[derive(Clone, Debug)]
 #[cfg_attr(
     docsrs,
@@ -37,10 +37,10 @@ pub struct LocalTime<F> {
 ///
 /// To format the current [local time] instead, use the [`LocalTime`] type.
 ///
-/// [local time]: https://docs.rs/time/0.3/time/struct.OffsetDateTime.html#method.now_local
-/// [UTC time]: https://docs.rs/time/0.3/time/struct.OffsetDateTime.html#method.now_utc
-/// [formatter]: https://docs.rs/time/0.3/time/formatting/trait.Formattable.html
-/// [`time` crate]: https://docs.rs/time/0.3/time/
+/// [local time]: time::OffsetDateTime::now_local
+/// [UTC time]:     time::OffsetDateTime::now_utc
+/// [formatter]:    time::formatting::Formattable
+/// [`time` crate]: time
 #[cfg_attr(docsrs, doc(cfg(feature = "time")))]
 #[derive(Clone, Debug)]
 pub struct UtcTime<F> {
@@ -55,8 +55,8 @@ pub struct UtcTime<F> {
 /// handle any errors. However, this also means the offset cannot change while the program is
 /// running (the offset will not change across DST changes).
 ///
-/// [formatter]: https://docs.rs/time/0.3/time/formatting/trait.Formattable.html
-/// [`time` crate]: https://docs.rs/time/0.3/time/
+/// [formatter]: time::formatting::Formattable
+/// [`time` crate]: time
 #[derive(Clone, Debug)]
 #[cfg_attr(docsrs, doc(cfg(feature = "time")))]
 pub struct OffsetTime<F> {
@@ -81,7 +81,7 @@ impl LocalTime<well_known::Rfc3339> {
     /// # drop(collector);
     /// ```
     ///
-    /// [local time]: https://docs.rs/time/0.3/time/struct.OffsetDateTime.html#method.now_local
+    /// [local time]: time::OffsetDateTime::now_local
     /// [RFC 3339]: https://datatracker.ietf.org/doc/html/rfc3339
     /// [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601
     pub fn rfc_3339() -> Self {
@@ -163,12 +163,12 @@ impl<F: Formattable> LocalTime<F> {
     /// # drop(collector);
     /// ```
     ///
-    /// [local time]: https://docs.rs/time/latest/time/struct.OffsetDateTime.html#method.now_local
-    /// [`time` crate]: https://docs.rs/time/0.3/time/
-    /// [`Formattable`]: https://docs.rs/time/0.3/time/formatting/trait.Formattable.html
-    /// [well-known formats]: https://docs.rs/time/0.3/time/format_description/well_known/index.html
-    /// [`format_description!`]: https://docs.rs/time/0.3/time/macros/macro.format_description.html
-    /// [`time::format_description::parse`]: https://docs.rs/time/0.3/time/format_description/fn.parse.html
+    /// [local time]: time::OffsetDateTime::now_local()
+    /// [`time` crate]: time
+    /// [`Formattable`]: time::formatting::Formattable
+    /// [well-known formats]: time::format_description::well_known
+    /// [`format_description!`]: time::macros::format_description!
+    /// [`time::format_description::parse`]: time::format_description::parse()
     /// [`time` book]: https://time-rs.github.io/book/api/format-description.html
     pub fn new(format: F) -> Self {
         Self { format }
@@ -212,7 +212,7 @@ impl UtcTime<well_known::Rfc3339> {
     /// # drop(collector);
     /// ```
     ///
-    /// [local time]: https://docs.rs/time/0.3/time/struct.OffsetDateTime.html#method.now_utc
+    /// [local time]: time::OffsetDateTime::now_utc
     /// [RFC 3339]: https://datatracker.ietf.org/doc/html/rfc3339
     /// [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601
     pub fn rfc_3339() -> Self {
@@ -280,12 +280,12 @@ impl<F: Formattable> UtcTime<F> {
     /// # drop(collector);
     /// ```
     ///
-    /// [UTC time]: https://docs.rs/time/latest/time/struct.OffsetDateTime.html#method.now_utc
-    /// [`time` crate]: https://docs.rs/time/0.3/time/
-    /// [`Formattable`]: https://docs.rs/time/0.3/time/formatting/trait.Formattable.html
-    /// [well-known formats]: https://docs.rs/time/0.3/time/format_description/well_known/index.html
-    /// [`format_description!`]: https://docs.rs/time/0.3/time/macros/macro.format_description.html
-    /// [`time::format_description::parse`]: https://docs.rs/time/0.3/time/format_description/fn.parse.html
+    /// [UTC time]: time::OffsetDateTime::now_utc()
+    /// [`time` crate]: time
+    /// [`Formattable`]: time::formatting::Formattable
+    /// [well-known formats]: time::format_description::well_known
+    /// [`format_description!`]: time::macros::format_description!
+    /// [`time::format_description::parse`]: time::format_description::parse
     /// [`time` book]: https://time-rs.github.io/book/api/format-description.html
     pub fn new(format: F) -> Self {
         Self { format }
@@ -357,7 +357,7 @@ impl OffsetTime<well_known::Rfc3339> {
     /// }
     /// ```
     ///
-    /// [local time offset]: https://docs.rs/time/0.3/time/struct.UtcOffset.html#method.current_local_offset
+    /// [local time offset]: time::UtcOffset::current_local_offset
     /// [RFC 3339]: https://datatracker.ietf.org/doc/html/rfc3339
     /// [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601
     pub fn local_rfc_3339() -> Result<Self, time::error::IndeterminateOffset> {
@@ -435,13 +435,13 @@ impl<F: time::formatting::Formattable> OffsetTime<F> {
     /// # drop(collector);
     /// ```
     ///
-    /// [`time` crate]: https://docs.rs/time/0.3/time/
-    /// [timezone offset]: https://docs.rs/time/latest/time/struct.UtcOffset.html
-    /// [`Formattable`]: https://docs.rs/time/0.3/time/formatting/trait.Formattable.html
-    /// [local offset]: https://docs.rs/time/0.3.5/time/struct.UtcOffset.html#method.current_local_offset
-    /// [well-known formats]: https://docs.rs/time/0.3/time/format_description/well_known/index.html
-    /// [`format_description!`]: https://docs.rs/time/0.3/time/macros/macro.format_description.html
-    /// [`time::format_description::parse`]: https://docs.rs/time/0.3/time/format_description/fn.parse.html
+    /// [`time` crate]: time
+    /// [timezone offset]: time::UtcOffset
+    /// [`Formattable`]: time::formatting::Formattable
+    /// [local offset]: time::UtcOffset::current_local_offset()
+    /// [well-known formats]: time::format_description::well_known
+    /// [`format_description!`]: time::macros::format_description
+    /// [`time::format_description::parse`]: time::format_description::parse
     /// [`time` book]: https://time-rs.github.io/book/api/format-description.html
     pub fn new(offset: time::UtcOffset, format: F) -> Self {
         Self { offset, format }

diff --git a/tracing-subscriber/src/layer/context.rs b/tracing-subscriber/src/layer/context.rs
@@ -26,7 +26,7 @@ use crate::{filter::FilterId, registry::Registry};
 /// ```
 ///
 /// [`Layer`]: super::Layer
-/// [`Subscriber`]: https://docs.rs/tracing-core/latest/tracing_core/trait.Subscriber.html
+/// [`Subscriber`]: tracing_core::Subscriber
 /// [stored data]: crate::registry::SpanRef
 /// [`LookupSpan`]: crate::registry::LookupSpan
 #[derive(Debug)]
@@ -99,9 +99,9 @@ where
     ///   check whether the event would be enabled. This allows `Layer`s to
     ///   elide constructing the event if it would not be recorded.
     ///
-    /// [register]: https://docs.rs/tracing-core/latest/tracing_core/subscriber/trait.Subscriber.html#method.register_callsite
-    /// [`enabled`]: https://docs.rs/tracing-core/latest/tracing_core/subscriber/trait.Subscriber.html#method.enabled
-    /// [`Context::enabled`]: #method.enabled
+    /// [register]: tracing_core::subscriber::Subscriber::register_callsite()
+    /// [`enabled`]: tracing_core::subscriber::Subscriber::enabled()
+    /// [`Context::enabled`]: Context::enabled()
     #[inline]
     pub fn event(&self, event: &Event<'_>) {
         if let Some(subscriber) = self.subscriber {

diff --git a/tracing-subscriber/src/layer/layered.rs b/tracing-subscriber/src/layer/layered.rs
@@ -18,7 +18,7 @@ use core::{any::TypeId, cmp, fmt, marker::PhantomData};
 /// [`Layer`]s.
 ///
 /// [`Layer`]: crate::Layer
-/// [`Subscriber`]: https://docs.rs/tracing-core/latest/tracing_core/trait.Subscriber.html
+/// [`Subscriber`]: tracing_core::Subscriber
 #[derive(Clone)]
 pub struct Layered<L, I, S = I> {
     /// The layer.