doc: Adopt intra doc links (#803)

This changes the docs build to nightly, which renders intra doc links.
`relay-wstring` already made use of them before, but the had not been
rendered on our deployed docs.

Author: jan-auer

.github/workflows/deploy.yml

@@ -13,14 +13,19 @@ jobs:
     name: Cargo Docs
     runs-on: ubuntu-latest
 
+    env:
+      RUSTDOCFLAGS: -Dbroken_intra_doc_links
+
     steps:
       - uses: actions/checkout@v2
         with:
           submodules: recursive
 
+      # compile with nightly for intra-doc-links
+      # see https://github.com/rust-lang/rfcs/blob/master/text/1946-intra-rustdoc-links.md
       - uses: actions-rs/toolchain@v1
         with:
-          toolchain: stable
+          toolchain: nightly
           profile: minimal
           components: rust-docs
           override: true
@@ -29,7 +34,13 @@ jobs:
         with:
           key: ${{ github.job }}
 
-      - run: make doc
+      - name: Build Docs
+        uses: actions-rs/cargo@v1
+        with:
+          command: doc
+          args: --workspace --all-features --no-deps
+
+      - run: echo '<meta http-equiv="refresh" content="0; url=relay/" />Redirecting to <a href="relay/">relay</a>' > target/doc/index.html
 
       - name: Deploy
         if: github.ref == 'refs/heads/master'

Makefile

@@ -72,8 +72,7 @@ doc: doc-api
 .PHONY: doc-api
 
 doc-api: setup-git
-	cargo doc --workspace --all-features --no-deps
-	@echo '<meta http-equiv="refresh" content="0; url=relay/" />Redirecting to <a href="relay/">relay</a>' > target/doc/index.html
+	cargo +nightly doc --workspace --all-features --no-deps
 .PHONY: doc-api
 
 # Style checking

relay-common/src/metrics.rs

@@ -14,7 +14,7 @@
 //! ## Initializing the Client
 //!
 //! Metrics can be used without initializing a statsd client. In that case, invoking `with_client`
-//! or the `metric!` macro will become a noop. Only when configured, metrics will actually be
+//! or the [`metric!`] macro will become a noop. Only when configured, metrics will actually be
 //! collected.
 //!
 //! To initialize the client, either use [`set_client`] to pass a custom client, or use
@@ -58,9 +58,6 @@
 //! ```
 //!
 //! [Metric Types]: https://github.com/statsd/statsd/blob/master/docs/metric_types.md
-//! [`set_client`]: fn.set_client.html
-//! [`configure_statsd`]: fn.configure_statsd.html
-//! [`metric!`]: ../macro.metric.html
 
 use std::collections::BTreeMap;
 use std::net::ToSocketAddrs;
@@ -158,7 +155,7 @@ pub fn configure_statsd<A: ToSocketAddrs>(
 /// Invoke a callback with the current statsd client.
 ///
 /// If statsd is not configured the callback is not invoked.  For the most part
-/// the `metric!` macro should be used instead.
+/// the [`metric!`] macro should be used instead.
 #[inline(always)]
 pub fn with_client<F, R>(f: F) -> R
 where
@@ -407,6 +404,8 @@ pub trait GaugeMetric {
 }
 
 /// Emits a metric.
+///
+/// See [module-level documentation](self) for examples.
 #[macro_export]
 macro_rules! metric {
     // counter increment

relay-common/src/project.rs

@@ -7,7 +7,7 @@ use serde::{Deserialize, Serialize};
 #[doc(inline)]
 pub use sentry_types::ProjectId;
 
-/// An error parsing [`ProjectKey`](struct.ProjectKey.html).
+/// An error parsing [`ProjectKey`].
 #[derive(Clone, Copy, Debug)]
 pub struct ParseProjectKeyError;
 

relay-ffi/src/lib.rs

@@ -98,8 +98,6 @@
 //! ```
 //!
 //! [`errno`]: https://man7.org/linux/man-pages/man3/errno.3.html
-//! [`catch_unwind`]: attr.catch_unwind.html
-//! [`with_last_error`]: fn.with_last_error.html
 
 #![warn(missing_docs)]
 
@@ -153,9 +151,7 @@ pub mod __internal {
 /// Acquires a reference to the last error and passes it to the callback, if any.
 ///
 /// Returns `Some(R)` if there was an error, otherwise `None`. The error resets when it is taken
-/// with [`take_error`].
-///
-/// [`take_error`]: fn.take_error.html
+/// with [`take_last_error`].
 ///
 /// # Example
 ///
@@ -184,8 +180,6 @@ where
 ///
 /// To inspect the error without removing it, use [`with_last_error`].
 ///
-/// [`with_last_error`]: fn.with_last_error.html
-///
 /// # Example
 ///
 /// ```
@@ -210,8 +204,6 @@ pub fn take_last_error() -> Option<failure::Error> {
 ///
 /// To capture panics, register the hook using [`set_panic_hook`].
 ///
-/// [`set_panic_hook`]: fn.set_panic_hook.html
-///
 /// # Example
 ///
 /// ```
@@ -282,7 +274,7 @@ impl Error for Panic {}
 /// This function must be registered early when the FFI is initialized before any other calls are
 /// made. Usually, this would be exported from an initialization function.
 ///
-/// See the [`Panic` documentation] for more information.
+/// See the [`Panic`] documentation for more information.
 ///
 /// # Example
 ///
@@ -291,8 +283,6 @@ impl Error for Panic {}
 ///     relay_ffi::set_panic_hook();
 /// }
 /// ```
-///
-/// [`Panic` documentation]: struct.Panic.html
 pub fn set_panic_hook() {
     panic::set_hook(Box::new(|info| set_last_error(Panic::new(info).into())));
 }

relay-filter/src/csp.rs

@@ -96,11 +96,12 @@ impl From<&str> for SchemeDomainPort {
 /// Checks if a url satisfies one of the specified origins.
 ///
 /// An origin specification may be in any of the following formats:
-///  - http://domain.com[:port]
+///
+///  - `http://domain.com[:port]`
 ///  - an exact match is required
-///  - * : anything goes
-///  - *.domain.com : matches domain.com and any subdomains
-///  - *:port : matches any hostname as long as the port matches
+///  - `*`: anything goes
+///  - `*.domain.com`: matches domain.com and any subdomains
+///  - `*:port`: matches any hostname as long as the port matches
 pub fn matches_any_origin(url: Option<&str>, origins: &[SchemeDomainPort]) -> bool {
     // if we have a "*" (Any) option, anything matches so don't bother going forward
     if origins

relay-general/src/protocol/contexts.rs

@@ -577,7 +577,7 @@ pub enum Context {
 impl Context {
     /// Represents the key under which a particular context type will be inserted in a Contexts object
     ///
-    /// See [Contexts.add](struct.Contexts.html)
+    /// See [`Contexts::add`]
     pub fn default_key(&self) -> Option<&'static str> {
         match &self {
             Context::Device(_) => Some(DeviceContext::default_key()),

relay-general/src/protocol/security_report.rs

@@ -814,6 +814,8 @@ pub struct Hpkp {
     /// The certificate chain, as served by the Known Pinned Host during TLS session setup.  It
     /// is provided as an array of strings; each string pem1, ... pemN is the Privacy-Enhanced Mail
     /// (PEM) representation of each X.509 certificate as described in [RFC7468].
+    ///
+    /// [RFC7468]: https://tools.ietf.org/html/rfc7468
     pub served_certificate_chain: Annotated<Array<String>>,
     /// The certificate chain, as constructed by the UA during certificate chain verification.
     pub validated_certificate_chain: Annotated<Array<String>>,

relay-general/src/user_agent.rs

@@ -4,10 +4,9 @@ pub use uaparser::{Device, UserAgent, OS};
 use uaparser::{Parser, UserAgentParser};
 
 lazy_static! {
-    /// The global [`UserAgentParser`]: https://docs.rs/uap-rs/0.2.2/uap_rs/struct.UserAgentParser.html
-    /// already configured with a user agent database.
+    /// The global [`UserAgentParser`] already configured with a user agent database.
     ///
-    /// For usage see [`Parser`]: https://docs.rs/uap-rs/0.2.2/uap_rs/trait.Parser.html
+    /// For usage, see [`Parser`].
     static ref UA_PARSER: UserAgentParser = {
         let ua_regexes = include_bytes!("../uap-core/regexes.yaml");
         UserAgentParser::from_bytes(ua_regexes).expect(

relay-server/src/actors/connector.rs

@@ -1,8 +1,6 @@
 //! Provides a metered client connector for upstream connections.
 //!
 //! See the [`MeteredConnector`] struct for more information.
-//!
-//! [`MeteredConnector`]: struct.MeteredConnector.html
 
 use std::sync::Arc;
 

relay-server/src/actors/controller.rs

@@ -1,8 +1,6 @@
 //! Defines an actor to control system run and shutdown.
 //!
 //! See the [`Controller`] struct for more information.
-//!
-//! [`Controller`]: struct.Controller.html
 
 use std::fmt;
 use std::time::Duration;
@@ -56,9 +54,6 @@ pub use crate::service::ServerError;
 ///     # System::current().stop()
 /// })
 /// ```
-///
-/// [`Subscribe`]: struct.Subscribe.html
-/// [`Shutdown`]: struct.Shutdown.html
 pub struct Controller {
     /// Configured timeout for graceful shutdowns.
     timeout: Duration,
@@ -198,8 +193,6 @@ impl Handler<signal::Signal> for Controller {
 }
 
 /// Configures the [`Controller`] with new parameters.
-///
-/// [`Controller`]: struct.Controller.html
 #[derive(Debug)]
 pub struct Configure {
     /// The maximum shutdown timeout before killing actors.
@@ -219,8 +212,6 @@ impl Handler<Configure> for Controller {
 }
 
 /// Subscribtion message for [`Shutdown`] events.
-///
-/// [`Shutdown`]: struct.Shutdown.html
 pub struct Subscribe(pub Recipient<Shutdown>);
 
 impl fmt::Debug for Subscribe {
@@ -252,8 +243,6 @@ impl Handler<Subscribe> for Controller {
 ///
 /// The return value is fully ignored. It is only `Result` such that futures can be executed inside
 /// a handler.
-///
-/// [`Controller`]: struct.Controller.html
 #[derive(Debug)]
 pub struct Shutdown {
     /// The timeout for this shutdown. `None` indicates an immediate forced shutdown.

relay-server/src/actors/events.rs

@@ -260,7 +260,7 @@ impl ProcessEnvelopeState {
 }
 
 /// Synchronous service for processing envelopes.
-struct EventProcessor {
+pub struct EventProcessor {
     config: Arc<Config>,
     #[cfg(feature = "processing")]
     rate_limiter: Option<RedisRateLimiter>,

relay-server/src/actors/mod.rs

@@ -1,26 +1,28 @@
 //! Defines all actors of the relay.
 //!
-//! Actors require an actix system to run. The system can be started using the [`Controller`]
-//! actor, which will also listen for shutdown signals and trigger a graceful shutdown. Note that
-//! actors must implement a handler for the [`Shutdown`] message and register with the controller
-//! to receive this signal. See the struct level documentation for more information.
+//! Actors require an actix system to run. The system can be started using the
+//! [`Controller`](controller::Controller) actor, which will also listen for shutdown signals and
+//! trigger a graceful shutdown. Note that actors must implement a handler for the
+//! [`Shutdown`](controller::Shutdown) message and register with the controller to receive this
+//! signal. See the struct level documentation for more information.
 //!
-//! The web server is wrapped by the [`Server`] actor. It starts the actix http web server and
-//! relays the graceful shutdown signal. Internally, it creates several other actors comprising the
-//! service state:
+//! The web server is wrapped by the [`Server`](server::Server) actor. It starts the actix http web
+//! server and relays the graceful shutdown signal. Internally, it creates several other actors
+//! comprising the service state:
 //!
-//!  - [`ProjectCache`] and [`KeyCache`]: Two caches that serve queries for project configurations
-//!    and relay public keys, respectively. Their requests are debounced and batched based on a
-//!    configured interval (100ms by default). Also, missing projects and keys are cached for some
-//!    time.
-//!  - [`EventManager`] and [`EventProcessor`]: Handle a queue of events, verify their projects,
-//!    execute PII stripping and finally send the event to the upstream. The processor is spawned
-//!    in multiple synchronous worker threads (via `SyncArbiter`).
-//!  - [`UpstreamRelay`]: Abstraction for communication with the upstream (either another Relay or
-//!    Sentry). It manages an internal client connector to throttle requests and ensures this relay
-//!    is authenticated before sending queries (e.g. project config or public keys).
+//!  - [`ProjectCache`](project_cache::ProjectCache): A cache that serves queries for project
+//!    configurations. Its requests are debounced and batched based on a configured interval (100ms
+//!    by default). Also, missing projects are cached for some time.
+//!  - [`EventManager`](events::EventManager) and [`EventProcessor`](events::EventProcessor): Handle
+//!    a queue of events, verify their projects, execute PII stripping and finally send the event to
+//!    the upstream. The processor is spawned in multiple synchronous worker threads (via
+//!    `SyncArbiter`).
+//!  - [`UpstreamRelay`](upstream::UpstreamRelay): Abstraction for communication with the upstream
+//!    (either another Relay or Sentry). It manages an internal client connector to throttle
+//!    requests and ensures this relay is authenticated before sending queries (e.g. project config
+//!    or public keys).
 //!
-//! ### Example
+//! # Example
 //!
 //! ```ignore
 //! use relay_server::controller::Controller;
@@ -29,15 +31,6 @@
 //! Controller::run(|| Server::start())
 //!     .expect("failed to start relay");
 //! ```
-//!
-//! [`Controller`]: controller/struct.Controller.html
-//! [`Shutdown`]: controller/struct.Shutdown.html
-//! [`Server`]: controller/struct.Server.html
-//! [`ProjectCache`]: controller/struct.ProjectCache.html
-//! [`KeyCache`]: controller/struct.KeyCache.html
-//! [`EventManager`]: controller/struct.EventManager.html
-//! [`EventProcessor`]: controller/struct.EventProcessor.html
-//! [`UpstreamRelay`]: controller/struct.UpstreamRelay.html
 
 pub mod connector;
 pub mod controller;

relay-server/src/lib.rs

@@ -4,9 +4,7 @@
 //! multiple supported endpoints, serves queries to downstream relays and send received events to
 //! the upstream.
 //!
-//! See the documentation of the `Config` struct for more information on configuration options.
-//!
-//! [`run`]: fn.run.html
+//! See the [`Config`] documentation for more information on configuration options.
 #![warn(missing_docs)]
 
 mod actors;