From ef4930c140c639eaaa0362662d90e55a31977eb3 Mon Sep 17 00:00:00 2001
From: Casper Meijn <casper@meijn.net>
Date: Fri, 31 May 2024 09:24:59 +0200
Subject: [PATCH] docs: Fix broken link warnings (#1056)

* docs: Fix broken link warnings

* ci: Check for documentation warnings
---
 .github/workflows/ci.yml                     | 20 ++++++++++++++++++++
 prost-build/src/code_generator/c_escaping.rs |  1 +
 prost-build/src/collections.rs               |  2 +-
 prost-build/src/config.rs                    |  2 +-
 prost-build/src/lib.rs                       |  6 ++++--
 prost/src/name.rs                            |  2 +-
 tests/src/lib.rs                             |  2 +-
 7 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e6905ea42..ae6518c6e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -20,6 +20,7 @@ jobs:
       - rustfmt
       - toml_validation
       - clippy
+      - docs
       - machete
       - unused_dependencies
       - test
@@ -69,6 +70,25 @@ jobs:
           components: clippy
       - run: cargo clippy --workspace --exclude protobuf --all-features --tests -- -D warnings
 
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: 'recursive'
+      - name: install protoc
+        uses: taiki-e/install-action@v2
+        with:
+          tool: protoc@${{ env.PROTOC_VERSION }}
+      - name: install ninja
+        uses: ./.github/actions/setup-ninja
+      - uses: dtolnay/rust-toolchain@stable
+      - name: "doc --lib --all-features"
+        run: |
+          cargo doc --lib --no-deps --all-features --document-private-items
+        env:
+          RUSTDOCFLAGS: -Dwarnings
+
   machete:
     runs-on: ubuntu-latest
     steps:
diff --git a/prost-build/src/code_generator/c_escaping.rs b/prost-build/src/code_generator/c_escaping.rs
index 58b2ede4e..44b0bfff2 100644
--- a/prost-build/src/code_generator/c_escaping.rs
+++ b/prost-build/src/code_generator/c_escaping.rs
@@ -1,6 +1,7 @@
 use log::debug;
 
 /// Based on [`google::protobuf::UnescapeCEscapeString`][1]
+///
 /// [1]: https://github.com/google/protobuf/blob/3.3.x/src/google/protobuf/stubs/strutil.cc#L312-L322
 pub(super) fn unescape_c_escape_string(s: &str) -> Vec<u8> {
     let src = s.as_bytes();
diff --git a/prost-build/src/collections.rs b/prost-build/src/collections.rs
index 63be4d627..5ac72fc54 100644
--- a/prost-build/src/collections.rs
+++ b/prost-build/src/collections.rs
@@ -13,7 +13,7 @@ pub(crate) enum MapType {
 #[non_exhaustive]
 #[derive(Default, Clone, Copy, Debug, PartialEq)]
 pub(crate) enum BytesType {
-    /// The [`alloc::collections::Vec::<u8>`] type.
+    /// The [`prost::alloc::vec::Vec<u8>`] type.
     #[default]
     Vec,
     /// The [`bytes::Bytes`] type.
diff --git a/prost-build/src/config.rs b/prost-build/src/config.rs
index a696e404b..0c3c6a75b 100644
--- a/prost-build/src/config.rs
+++ b/prost-build/src/config.rs
@@ -1015,7 +1015,7 @@ impl Config {
     ///
     /// This is generally used when control over the output should not be managed by Prost,
     /// such as in a flow for a `protoc` code generating plugin. When compiling as part of a
-    /// `build.rs` file, instead use [`compile_protos()`].
+    /// `build.rs` file, instead use [`Self::compile_protos()`].
     pub fn generate(
         &mut self,
         requests: Vec<(Module, FileDescriptorProto)>,
diff --git a/prost-build/src/lib.rs b/prost-build/src/lib.rs
index e3659a2c5..222440dbf 100644
--- a/prost-build/src/lib.rs
+++ b/prost-build/src/lib.rs
@@ -257,8 +257,6 @@ pub fn compile_protos(protos: &[impl AsRef<Path>], includes: &[impl AsRef<Path>]
 /// This function can be combined with a crate like [`protox`] which outputs a
 /// [`FileDescriptorSet`] and is a pure Rust implementation of `protoc`.
 ///
-/// [`protox`]: https://github.com/andrewhickman/protox
-///
 /// # Example
 /// ```rust,no_run
 /// # use prost_types::FileDescriptorSet;
@@ -269,6 +267,10 @@ pub fn compile_protos(protos: &[impl AsRef<Path>], includes: &[impl AsRef<Path>]
 ///   prost_build::compile_fds(file_descriptor_set)
 /// }
 /// ```
+///
+/// [`protox`]: https://github.com/andrewhickman/protox
+/// [1]: https://doc.rust-lang.org/std/macro.include.html
+/// [2]: http://doc.crates.io/build-script.html#case-study-code-generation
 pub fn compile_fds(fds: FileDescriptorSet) -> Result<()> {
     Config::new().compile_fds(fds)
 }
diff --git a/prost/src/name.rs b/prost/src/name.rs
index 1e4a36e98..1b5b4a28e 100644
--- a/prost/src/name.rs
+++ b/prost/src/name.rs
@@ -27,7 +27,7 @@ pub trait Name: Message {
     /// Type URL for this [`Message`], which by default is the full name with a
     /// leading slash, but may also include a leading domain name, e.g.
     /// `type.googleapis.com/google.profile.Person`.
-    /// This can be used when serializing with the [`Any`] type.
+    /// This can be used when serializing into the `google.protobuf.Any` type.
     fn type_url() -> String {
         format!("/{}", Self::full_name())
     }
diff --git a/tests/src/lib.rs b/tests/src/lib.rs
index f0f69c84c..a30749e0e 100644
--- a/tests/src/lib.rs
+++ b/tests/src/lib.rs
@@ -115,7 +115,7 @@ pub mod oneof_attributes {
     include!(concat!(env!("OUT_DIR"), "/foo.custom.one_of_attrs.rs"));
 }
 
-/// Issue https://github.com/tokio-rs/prost/issues/118
+/// Issue <https://github.com/tokio-rs/prost/issues/118>
 ///
 /// When a message contains an enum field with a default value, we
 /// must ensure that the appropriate name conventions are used.