Fix doc-links and run Rustdoc as part of the infra check suite (#694)

Part of #155

Author: Xanewok

crates/codegen/language/definition/src/internals/parse_input_tokens/mod.rs

@@ -18,7 +18,7 @@ pub trait ParseInputTokens: Sized {
         Self::parse_value(input, errors)
     }
 
-    /// Allows implementations (like 'Option<T>') to modify the parsing logic,
+    /// Allows implementations (like `Option<T>`) to modify the parsing logic,
     /// by checking if the field exists before attempting to parse it.
     fn parse_field(name: &str, input: ParseStream, errors: &mut ErrorsCollection) -> Result<Self> {
         ParseHelpers::field(name, input, errors)

crates/codegen/parser/runtime/src/support/choice_helper.rs

@@ -79,18 +79,6 @@ impl ChoiceHelper {
     /// Executes a closure that allows the caller to drive the choice parse.
     ///
     /// Useful when you want to eagerly return a result from the parse function (e.g. when the choice was fully matched).
-    ///
-    /// Usage:
-    /// ```no_run
-    /// # use codegen_parser_runtime::support::{ParserResult, ChoiceHelper, Stream};
-    /// # fn parse_something() -> ParserResult { ParserResult::r#match(vec![], vec![]) }
-    /// # fn parse_another() -> ParserResult { ParserResult::r#match(vec![], vec![]) }
-    /// ChoiceHelper::run(input, |mut choice| {
-    ///     choice.consider(parse_something()).pick_or_backtrack(input)?;
-    ///     choice.consider(parse_another()).pick_or_backtrack(input)?;
-    ///     choice.finish(input)
-    /// });
-    /// ```
     pub fn run(
         input: &mut ParserContext,
         f: impl FnOnce(Self, &mut ParserContext) -> ControlFlow<ParserResult, Self>,
@@ -105,7 +93,7 @@ impl ChoiceHelper {
 
     /// Aggregates a choice result into the accumulator.
     ///
-    /// Returns a [`Choice`] struct that can be used to either pick the value or backtrack the input.
+    /// If a value is considered as a full match, it is returned, otherwise we backtrack and continue.
     pub fn consider(
         &mut self,
         input: &mut ParserContext,

crates/codegen/parser/runtime/src/support/sequence_helper.rs

@@ -169,18 +169,6 @@ impl SequenceHelper {
     /// Executes a closure that allows the caller to drive the sequence parse.
     ///
     /// Useful when you want to eagerly return a result from the parse function (e.g. when we can't make more progress).
-    ///
-    /// Usage:
-    /// ```no_run
-    /// # use codegen_parser_runtime::support::{ParserResult, SequenceHelper};
-    /// # fn parse_something() -> ParserResult { ParserResult::r#match(vec![], vec![]) }
-    /// # fn parse_another() -> ParserResult { ParserResult::r#match(vec![], vec![]) }
-    /// SequenceHelper::run(|mut sequence| {
-    ///     sequence.elem(parse_something())?;
-    ///     sequence.elem(parse_another())?;
-    ///     sequence.finish()
-    /// });
-    /// ```
     pub fn run(f: impl FnOnce(Self) -> ControlFlow<ParserResult, Self>) -> ParserResult {
         match f(SequenceHelper::default()) {
             ControlFlow::Break(result) => result,

crates/codegen/spec/src/lib.rs

@@ -7,7 +7,7 @@
 //!
 //! and the auxiliary snippet files included by the grammar mkdocs pages.
 //!
-//! Exposes a [`SpecGeneratorExtensions`] trait that generates all the pages in a given [`CodegenContext`].
+//! Exposes a [`SpecGeneratorExtensions`] trait that generates all the pages in a given [`Codegen`] context.
 mod grammar;
 mod markdown;
 mod navigation;

crates/infra/cli/generated/infra.zsh-completions

@@ -26,6 +26,8 @@ impl CheckController {
 enum CheckCommand {
     /// Run 'cargo check' for all crates, features, and targets.
     Cargo,
+    /// Run `cargo doc` to generate Rustdoc documentation and check for any broken links.
+    Rustdoc,
     /// Check NPM packages for any outdated codegen steps.
     Npm,
     /// Check mkdocs documentation for any build issues or broken links.
@@ -38,14 +40,27 @@ impl OrderedCommand for CheckCommand {
 
         match self {
             CheckCommand::Cargo => check_cargo(),
+            CheckCommand::Rustdoc => check_rustdoc(),
             CheckCommand::Npm => check_npm(),
             CheckCommand::Mkdocs => check_mkdocs(),
         }
     }
 }
 
 fn check_cargo() -> Result<()> {
-    CargoWorkspace::get_command("check")?.run()
+    CargoWorkspace::get_command("check")?
+        .flag("--all-targets")
+        .run()
+}
+
+fn check_rustdoc() -> Result<()> {
+    CargoWorkspace::get_command("doc")?
+        .flag("--no-deps")
+        .flag("--document-private-items")
+        .flag("--lib")
+        .flag("--bins")
+        .flag("--examples")
+        .run()
 }
 
 fn check_npm() -> Result<()> {

crates/infra/cli/src/commands/check/mod.rs

@@ -65,7 +65,9 @@ impl OrderedCommand for LintCommand {
 }
 
 fn run_clippy() -> Result<()> {
-    CargoWorkspace::get_command("clippy")?.run()
+    CargoWorkspace::get_command("clippy")?
+        .flag("--all-targets")
+        .run()
 }
 
 fn run_cargo_fmt() -> Result<()> {

crates/infra/cli/src/commands/lint/mod.rs

@@ -99,10 +99,11 @@ impl CargoWorkspace {
     }
 
     pub fn get_command(subcommand: impl AsRef<str>) -> Result<Command> {
+        let subcommand = subcommand.as_ref();
+
         let mut command = Command::new("cargo")
-            .arg(subcommand.as_ref())
-            .flag("--all")
-            .flag("--all-targets")
+            .arg(subcommand)
+            .flag("--workspace")
             .flag("--all-features");
 
         if GitHub::is_running_in_ci() {
@@ -115,6 +116,15 @@ impl CargoWorkspace {
                     rustflags = serde_json::to_string(&["--deny", "warnings"])?,
                 ),
             );
+            // Rustdoc requires specifying RUSTDOCFLAGS, instead:
+            // See <https://github.com/rust-lang/cargo/issues/8424#issuecomment-1070988443>.
+            command = command.property(
+                "--config",
+                format!(
+                    "build.rustdocflags = {rustdocflags}",
+                    rustdocflags = serde_json::to_string(&["--deny", "warnings"])?,
+                ),
+            );
         }
 
         Ok(command)