Fix check-rust-docs warnings (#2436)

* Fix rust-doc warnings

* Allow lint for public links to private items across all crates

* Enforce check-rust-docs success in CI

* Update schema file, remove TODO from rustdoc

.github/workflows/ci.yaml

@@ -169,7 +169,7 @@ jobs:
     if: ${{needs.changed_files.outputs.rs_changed == 'true' || needs.changed_files.outputs.ci_changed == 'true'}}
     env:
       # enables the creation of a workspace index.html page.
-      RUSTDOCFLAGS: "--enable-index-page -Zunstable-options"
+      RUSTDOCFLAGS: "--enable-index-page -Zunstable-options -Dwarnings"
     steps:
       - uses: actions/checkout@v3
       - uses: arduino/setup-protoc@v1
@@ -545,6 +545,7 @@ jobs:
         test_agent,
         lint,
         lint_markdown,
+        check-rust-docs,
       ]
     runs-on: ubuntu-latest
     steps:
@@ -562,5 +563,6 @@ jobs:
             (needs.lint.result == 'success' || needs.lint.result == 'skipped') &&
             (needs.lint_markdown.result == 'success' || needs.lint_markdown.result == 'skipped') &&
             (needs.intellij_e2e_on_release_branch.result == 'success' || needs.intellij_e2e_on_release_branch.result == 'skipped') &&
-            (needs.vscode_e2e_on_release_branch.result == 'success' || needs.vscode_e2e_on_release_branch.result == 'skipped') }}
+            (needs.vscode_e2e_on_release_branch.result == 'success' || needs.vscode_e2e_on_release_branch.result == 'skipped') &&
+            (needs.check-rust-docs.result == 'success' || needs.check-rust-docs.result == 'skipped') }}
         run: echo $CI_SUCCESS && if [ "$CI_SUCCESS" == "true" ]; then echo "SUCCESS" && exit 0; else echo "Failure" && exit 1; fi

Cargo.toml

@@ -80,6 +80,9 @@ once_cell = "1"
 exec = "0.3"
 drain = "0.1"
 
+[workspace.lints.rustdoc]
+private_intra_doc_links = "allow"
+
 [profile.release]
 strip = "debuginfo"
 # Enabling LTO causes this issue https://github.com/metalbear-co/mirrord/issues/906

changelog.d/1399.internal.md

@@ -0,0 +1 @@
+Fix all check-rust-docs warnings

medschool/Cargo.toml

@@ -13,6 +13,9 @@ categories.workspace = true
 publish.workspace = true
 edition.workspace = true
 
+[lints]
+workspace = true
+
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]

medschool/src/main.rs

@@ -41,7 +41,8 @@ enum DocsError {
     #[error("IO error {0}")]
     IO(#[from] std::io::Error),
 
-    /// May happen (probably never) when [`parse_files`] is reading the source file into a `&str`.
+    /// May happen (probably never) when [`files_to_string`] is reading the source file into a
+    /// `&str`.
     #[error("Read past end of source!")]
     ReadOutOfBounds,
 }
@@ -416,7 +417,7 @@ fn parse_docs_into_tree(files: Vec<syn::File>) -> Result<BTreeSet<PartialType>,
     Ok(type_docs)
 }
 
-/// Digs into the [`PartialTypes`] building new types that inline the types of their
+/// Digs into the [`PartialType`] building new types that inline the types of their
 /// [`PartialField`]s, turning something like:
 ///
 /// ```no_run
@@ -570,7 +571,7 @@ struct ToolArgs {
 
 /// # Attention when using `RUST_LOG`
 ///
-/// Every function here supports our usual [`tracing::instrument`] setup, with default
+/// Every function here supports our usual [`mod@tracing::instrument`] setup, with default
 /// `log_level = "trace`, but if you dare run with `RUST_LOG=trace` you're going to have a bad time!
 ///
 /// The logging is put in place so you can quickly change whatever function you need to

mirrord-schema.json

@@ -567,7 +567,7 @@
       "properties": {
         "tcp_ping4_mock": {
           "title": "experimental {#fexperimental-tcp_ping4_mock}",
-          "description": "https://github.com/metalbear-co/mirrord/issues/2421#issuecomment-2093200904",
+          "description": "<https://github.com/metalbear-co/mirrord/issues/2421#issuecomment-2093200904>",
           "type": [
             "boolean",
             "null"
@@ -775,7 +775,7 @@
         },
         "ignore_localhost": {
           "title": "ignore_localhost",
-          "description": "Consider removing when adding https://github.com/metalbear-co/mirrord/issues/702",
+          "description": "Consider removing when adding <https://github.com/metalbear-co/mirrord/issues/702>",
           "type": [
             "boolean",
             "null"

mirrord/agent/Cargo.toml

@@ -12,6 +12,10 @@ keywords.workspace = true
 categories.workspace = true
 publish.workspace = true
 edition.workspace = true
+
+[lints]
+workspace = true
+
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]

mirrord/agent/src/cgroup.rs

@@ -323,8 +323,8 @@ impl CgroupV2 {
     }
 }
 
-/// V1 Docs: https://docs.kernel.org/admin-guide/cgroup-v1/index.html
-/// V2 Docs: https://docs.kernel.org/admin-guide/cgroup-v2.html
+/// V1 Docs: <https://docs.kernel.org/admin-guide/cgroup-v1/index.html>
+/// V2 Docs: <https://docs.kernel.org/admin-guide/cgroup-v2.html>
 #[derive(Debug)]
 pub(crate) enum Cgroup {
     V1(CgroupV1),

mirrord/agent/src/env.rs

@@ -78,7 +78,7 @@ impl EnvFilter {
     }
 }
 
-/// Translate ToIter<AsRef<str>> of "K=V" to HashMap.
+/// Translate `ToIter<AsRef<str>>` of "K=V" to HashMap.
 pub(crate) fn parse_raw_env<'a, S: AsRef<str> + 'a + ?Sized, T: IntoIterator<Item = &'a S>>(
     raw: T,
 ) -> HashMap<String, String> {

mirrord/agent/src/http.rs

@@ -23,9 +23,9 @@ impl HttpVersion {
     pub const MINIMAL_HEADER_SIZE: usize = 10;
 
     /// Checks if `buffer` contains a prefix of a valid HTTP/1.x request, or if it could be an
-    /// HTTP/2 request by comparing it with a slice of [`H2_PREFACE`].
+    /// HTTP/2 request by comparing it with a slice of [`Self::H2_PREFACE`].
     ///
-    /// The given `buffer` must contain at least [`MINIMAL_HEADER_SIZE`] bytes, otherwise this
+    /// The given `buffer` must contain at least [`Self::MINIMAL_HEADER_SIZE`] bytes, otherwise this
     /// function always returns [`None`].
     #[tracing::instrument(level = "trace")]
     pub fn new(buffer: &[u8]) -> Option<Self> {

mirrord/agent/src/sniffer.rs

@@ -48,11 +48,11 @@ pub(crate) struct TcpSessionIdentifier {
     ///
     /// You can get this IP by checking `kubectl get pod -o wide`.
     ///
-    /// ```sh`
+    /// ```sh
     /// $ kubectl get pod -o wide
     /// NAME        READY   STATUS    IP
     /// happy-pod   1/1     Running   1.2.3.4   
-    /// ````
+    /// ```
     dest_addr: Ipv4Addr,
     source_port: u16,
     dest_port: u16,

mirrord/agent/src/steal/api.rs

@@ -85,7 +85,7 @@ impl TcpStealerApi {
     /// Helper function that passes the [`DaemonTcp`] messages we generated in the
     /// [`TcpConnectionStealer`] task, back to the agent.
     ///
-    /// Called in the [`ClientConnectionHandler`].
+    /// Called in the `ClientConnectionHandler`.
     #[tracing::instrument(level = "trace", skip(self))]
     pub(crate) async fn recv(&mut self) -> Result<DaemonTcp> {
         match self.daemon_rx.recv().await {
@@ -122,7 +122,7 @@ impl TcpStealerApi {
             .await
     }
 
-    /// Handles the conversion of [`LayerTcpSteal::TcpData`], that is passed from the
+    /// Handles the conversion of [`TcpData`], that is passed from the
     /// agent, to an internal stealer command [`Command::ResponseData`].
     ///
     /// The actual handling of this message is done in [`TcpConnectionStealer`].

mirrord/agent/src/steal/connections/filtered.rs

@@ -342,7 +342,7 @@ pub struct FilteredStealTask<T> {
     /// 3. `None` -> client does not know about this connection at all
     ///
     /// Used to send [`ConnectionMessageOut::Closed`] in [`Self::run`] when
-    /// [`Self::run_until_upgrade`] and [`Self::run_after_upgrade`] have finished.
+    /// [`Self::run_until_http_ends`] and [`Self::run_after_http_ends`] have finished.
     subscribed: HashMap<ClientId, bool>,
 
     /// For receiving [`Request`]s extracted by the [`FilteringService`].

mirrord/agent/src/steal/http/reversible_stream.rs

@@ -14,7 +14,7 @@ use tokio::{
 /// Wraps a [`TcpStream`] to allow a sort of _peek_ functionality, by reading the first bytes, but
 /// then keeping them for later reads.
 ///
-/// Very useful to the HTTP filter component on [`stealer`], where we have to look at the first
+/// Very useful to the HTTP filter component on `stealer`, where we have to look at the first
 /// message on a [`TcpStream`] to try and identify if this connection is _talking_ HTTP.
 ///
 /// Thanks [finomnis](https://stackoverflow.com/users/2902833/finomnis) for the help!
@@ -31,17 +31,17 @@ pub(crate) struct ReversibleStream<const HEADER_SIZE: usize> {
     /// So we need to always know how many bytes we actually have.
     header_len: usize,
 
-    /// How many bytes out of the [`header`] were already read by the reader of this
+    /// How many bytes out of the `header` were already read by the reader of this
     /// [`ReversibleStream`]. If the reader reads bytes into a buffer that is smaller than
-    /// `HEADER_SIZE`, it would not read the whole [`header`] on the first read, so this is the
-    /// amount of bytes that were already read. After all the bytes from the [`header`] were read,
+    /// `HEADER_SIZE`, it would not read the whole `header` on the first read, so this is the
+    /// amount of bytes that were already read. After all the bytes from the `header` were read,
     /// by the user of this struct, further reads are forwarded to the underlying `TcpStream`.
     num_forwarded: usize,
 }
 
 impl<const HEADER_SIZE: usize> ReversibleStream<HEADER_SIZE> {
-    /// Build a Reversible stream from a TcpStream, move on if not done within given timeout.
-    /// Return an Error if there was an error while reading from the TCP Stream.
+    /// Build a [`ReversibleStream`] from a [`TcpStream`], move on if not done within given timeout.
+    /// Return an Error if there was an error while reading from the [`TcpStream`].
     pub(crate) async fn read_header(stream: TcpStream, timeout: Duration) -> io::Result<Self> {
         let mut this = Self {
             stream,

mirrord/analytics/Cargo.toml

@@ -13,6 +13,8 @@ categories.workspace = true
 publish.workspace = true
 edition.workspace = true
 
+[lints]
+workspace = true
 
 [dependencies]
 base64 = "0.21"

mirrord/auth/Cargo.toml

@@ -13,6 +13,9 @@ categories.workspace = true
 publish.workspace = true
 edition.workspace = true
 
+[lints]
+workspace = true
+
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [features]

mirrord/auth/src/credentials.rs

@@ -79,7 +79,7 @@ pub trait LicenseValidity {
     /// expiration date of `today + 3` means we have 2 days left until expiry.
     fn days_until_expiration(&self) -> Option<u64>;
 
-    /// Converts a [`NaiveDate`] into a [`NaiveDateTime`], so we can turn it into a
+    /// Converts a [`NaiveDate`] into a [`DateTime`], so we can turn it into a
     /// [`DateTime<UTC>`] to check a license's validity.
     ///
     /// I(alex) think this might cause trouble with potential mismatched timezone offsets, but

mirrord/cli/Cargo.toml

@@ -13,6 +13,9 @@ categories.workspace = true
 publish.workspace = true
 edition.workspace = true
 
+[lints]
+workspace = true
+
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]

mirrord/cli/src/config.rs

@@ -169,7 +169,7 @@ pub(super) struct ExecArgs {
     #[arg(long)]
     pub no_udp_outgoing: bool,
 
-    /// Disable telemetry. See https://github.com/metalbear-co/mirrord/blob/main/TELEMETRY.md
+    /// Disable telemetry. See <https://github.com/metalbear-co/mirrord/blob/main/TELEMETRY.md>
     #[arg(long)]
     pub no_telemetry: bool,
 
@@ -199,7 +199,7 @@ pub(super) enum OperatorCommand {
     /// NOTE: You don't need to install the operator to use open source mirrord features.
     #[command(override_usage = "mirrord operator setup [OPTIONS] | kubectl apply -f -")]
     Setup {
-        /// ToS can be read here https://metalbear.co/legal/terms
+        /// ToS can be read here <https://metalbear.co/legal/terms>
         #[arg(long)]
         accept_tos: bool,
 
@@ -310,7 +310,7 @@ pub(super) struct ExtensionExecArgs {
     pub executable: Option<String>,
 }
 
-/// Args for the [`super::verify_config`] mirrord-cli command.
+/// Args for the [`mod@super::verify_config`] mirrord-cli command.
 #[derive(Args, Debug)]
 #[command(group(ArgGroup::new("verify-config")))]
 pub(super) struct VerifyConfigArgs {

mirrord/cli/src/execution.rs

@@ -207,7 +207,7 @@ impl MirrordExecution {
             format!("127.0.0.1:{port}"),
         );
 
-        // Fix https://github.com/metalbear-co/mirrord/issues/1745
+        // Fix <https://github.com/metalbear-co/mirrord/issues/1745>
         // by disabling the fork safety check in the Objective-C runtime.
         #[cfg(target_os = "macos")]
         env_vars.insert(
@@ -347,7 +347,7 @@ impl MirrordExecution {
     /// Required when called from extension since sometimes the extension
     /// cleans up the process when the parent process exits, so we need the parent to stay alive
     /// while the internal proxy is running.
-    /// See https://github.com/metalbear-co/mirrord/issues/1211
+    /// See <https://github.com/metalbear-co/mirrord/issues/1211>
     pub(crate) async fn wait(mut self) -> Result<()> {
         self.child
             .wait()

mirrord/cli/src/internal_proxy.rs

@@ -8,7 +8,7 @@
 //! (previously was solved using envguard which wasn't good enough)
 //!
 //! The proxy will either directly connect to an existing agent (currently only used for tests),
-//! or let the [`OperatorApi`] handle the connection.
+//! or let the [`OperatorApi`](mirrord_operator::client::OperatorApi) handle the connection.
 
 use std::{
     env,
@@ -108,7 +108,7 @@ async fn request_pause(
 /// Creates a listening socket using socket2
 /// to control the backlog and manage scenarios where
 /// the proxy is under heavy load.
-/// https://github.com/metalbear-co/mirrord/issues/1716#issuecomment-1663736500
+/// <https://github.com/metalbear-co/mirrord/issues/1716#issuecomment-1663736500>
 /// in macOS backlog is documented to be hardcoded limited to 128.
 fn create_listen_socket() -> Result<TcpListener, InternalProxySetupError> {
     let socket = socket2::Socket::new(

mirrord/cli/src/verify_config.rs

@@ -1,6 +1,7 @@
-//! `mirrord verify-config [--ide] {path}` builds a [`VerifyConfig`] enum after checking the
-//! config file passed in `path`. It's used by the IDE plugins to display errors/warnings quickly,
-//! without having to start mirrord-layer.
+//! `mirrord verify-config [--ide] {path}` builds a
+//! [`VerifyConfig`](crate::Commands::VerifyConfig) enum after checking the config file passed in
+//! `path`. It's used by the IDE plugins to display errors/warnings quickly, without having to start
+//! mirrord-layer.
 use error::Result;
 use mirrord_config::{
     config::{ConfigContext, MirrordConfig},

mirrord/config/Cargo.toml

@@ -13,6 +13,9 @@ categories.workspace = true
 publish.workspace = true
 edition.workspace = true
 
+[lints]
+workspace = true
+
 [dependencies]
 mirrord-config-derive = { path = "./derive"}
 mirrord-analytics = { path = "../analytics"}

mirrord/config/derive/Cargo.toml

@@ -13,6 +13,9 @@ categories.workspace = true
 publish.workspace = true
 edition.workspace = true
 
+[lints]
+workspace = true
+
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 [lib]
 proc-macro = true

mirrord/config/src/experimental.rs

@@ -12,7 +12,7 @@ use crate::config::source::MirrordConfigSource;
 pub struct ExperimentalConfig {
     /// ## experimental {#fexperimental-tcp_ping4_mock}
     ///
-    /// https://github.com/metalbear-co/mirrord/issues/2421#issuecomment-2093200904
+    /// <https://github.com/metalbear-co/mirrord/issues/2421#issuecomment-2093200904>
     #[config(default = true)]
     pub tcp_ping4_mock: bool,
 }

mirrord/config/src/feature/fs.rs

@@ -5,7 +5,7 @@
 //! or disable file operations;
 //!
 //! 2. [`FsUserConfig::Advanced`]: All of the above, plus allows setting up
-//! [`mirrord_layer::file::filter::FileFilter`] to control which files should be opened
+//! `mirrord_layer::file::filter::FileFilter` to control which files should be opened
 //! locally or remotely.
 use schemars::JsonSchema;
 use serde::Deserialize;

mirrord/config/src/feature/network/incoming.rs

@@ -195,7 +195,7 @@ pub struct IncomingAdvancedFileConfig {
 
     /// ### ignore_localhost
     ///
-    /// Consider removing when adding https://github.com/metalbear-co/mirrord/issues/702
+    /// Consider removing when adding <https://github.com/metalbear-co/mirrord/issues/702>
     pub ignore_localhost: Option<bool>,
 
     /// ### ignore_ports

mirrord/console/Cargo.toml

@@ -13,6 +13,9 @@ categories.workspace = true
 publish.workspace = true
 edition.workspace = true
 
+[lints]
+workspace = true
+
 [[bin]]
 name = "mirrord-console"
 required-features = ["binary"]

mirrord/console/src/async_logger.rs

@@ -52,8 +52,8 @@ impl LoggerTask {
 }
 
 /// Console logger that sends log messages to the console app using
-/// [`codec`](mirrord_intproxy::codec). It uses a background [`tokio::task`] to send messages with
-/// an [`AsyncEncoder`].
+/// [`codec`](mirrord_intproxy_protocol::codec). It uses a background [`tokio::task`] to send
+/// messages with an [`AsyncEncoder`].
 pub struct AsyncConsoleLogger {
     tx: Sender<Record>,
 }