Merge pull request #2674 from ehuss/fix-missing-docs

Clean up some missing docs

Author: ehuss

.github/workflows/main.yml

@@ -98,6 +98,18 @@ jobs:
       - run: rustup component add clippy
       - run: cargo clippy --workspace --all-targets --no-deps -- -D warnings
 
+  docs:
+    name: Check API docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust
+        run: bash ci/install-rust.sh stable x86_64-unknown-linux-gnu
+      - name: Ensure intradoc links are valid
+        run: cargo doc --workspace --document-private-items --no-deps
+        env:
+          RUSTDOCFLAGS: -D warnings
+
   # The success job is here to consolidate the total success/failure state of
   # all other jobs. This job is then included in the GitHub branch protection
   # rule which prevents merges unless all other jobs are passing. This makes
@@ -112,6 +124,7 @@ jobs:
       - aarch64-cross-builds
       - gui
       - clippy
+      - docs
     runs-on: ubuntu-latest
     steps:
       - run: jq --exit-status 'all(.result == "success")' <<< '${{ toJson(needs) }}'

src/renderer/html_handlebars/hbs_renderer.rs

@@ -20,10 +20,12 @@ use once_cell::sync::Lazy;
 use regex::{Captures, Regex};
 use serde_json::json;
 
+/// The HTML renderer for mdBook.
 #[derive(Default)]
 pub struct HtmlHandlebars;
 
 impl HtmlHandlebars {
+    /// Returns a new instance of [`HtmlHandlebars`].
     pub fn new() -> Self {
         HtmlHandlebars
     }

src/renderer/html_handlebars/mod.rs

@@ -1,5 +1,3 @@
-#![allow(missing_docs)] // FIXME: Document this
-
 pub use self::hbs_renderer::HtmlHandlebars;
 pub use self::static_files::StaticFiles;
 

src/utils/fs.rs

@@ -1,3 +1,5 @@
+//! Filesystem utilities and helpers.
+
 use crate::errors::*;
 use log::{debug, trace};
 use std::fs::{self, File};
@@ -202,6 +204,7 @@ fn copy<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> Result<()> {
     }
 }
 
+/// Returns the name of the file used for HTTP 404 "not found" with the `.html` extension.
 pub fn get_404_output_file(input_404: &Option<String>) -> String {
     input_404
         .as_ref()

src/utils/mod.rs

@@ -1,4 +1,4 @@
-#![allow(missing_docs)] // FIXME: Document this
+//! Various helpers and utilities.
 
 pub mod fs;
 mod string;
@@ -194,6 +194,7 @@ pub fn render_markdown(text: &str, smart_punctuation: bool) -> String {
     render_markdown_with_path(text, smart_punctuation, None)
 }
 
+/// Creates a new pulldown-cmark parser of the given text.
 pub fn new_cmark_parser(text: &str, smart_punctuation: bool) -> Parser<'_> {
     let mut opts = Options::empty();
     opts.insert(Options::ENABLE_TABLES);
@@ -207,6 +208,11 @@ pub fn new_cmark_parser(text: &str, smart_punctuation: bool) -> Parser<'_> {
     Parser::new_ext(text, opts)
 }
 
+/// Renders markdown to HTML.
+///
+/// `path` should only be set if this is being generated for the consolidated
+/// print page. It should point to the page being rendered relative to the
+/// root of the book.
 pub fn render_markdown_with_path(
     text: &str,
     smart_punctuation: bool,