From 3f0403dd680e981927bc0e9a2773d1dd131350a0 Mon Sep 17 00:00:00 2001 From: Igor Matuszewski Date: Mon, 4 Dec 2023 21:19:52 +0100 Subject: [PATCH 1/4] Fix broken doc-links --- crates/codegen/parser/runtime/src/support/choice_helper.rs | 2 +- crates/codegen/spec/src/lib.rs | 2 +- .../outputs/cargo/crate/src/generated/support/choice_helper.rs | 2 +- .../outputs/npm/crate/src/generated/support/choice_helper.rs | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/crates/codegen/parser/runtime/src/support/choice_helper.rs b/crates/codegen/parser/runtime/src/support/choice_helper.rs index e877d7ef6b..4814471648 100644 --- a/crates/codegen/parser/runtime/src/support/choice_helper.rs +++ b/crates/codegen/parser/runtime/src/support/choice_helper.rs @@ -105,7 +105,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, diff --git a/crates/codegen/spec/src/lib.rs b/crates/codegen/spec/src/lib.rs index a9747cb5cb..3e9404d9d5 100644 --- a/crates/codegen/spec/src/lib.rs +++ b/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; diff --git a/crates/solidity/outputs/cargo/crate/src/generated/support/choice_helper.rs b/crates/solidity/outputs/cargo/crate/src/generated/support/choice_helper.rs index af1a5c4a66..8c254a7a6a 100644 --- a/crates/solidity/outputs/cargo/crate/src/generated/support/choice_helper.rs +++ b/crates/solidity/outputs/cargo/crate/src/generated/support/choice_helper.rs @@ -107,7 +107,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, diff --git a/crates/solidity/outputs/npm/crate/src/generated/support/choice_helper.rs b/crates/solidity/outputs/npm/crate/src/generated/support/choice_helper.rs index af1a5c4a66..8c254a7a6a 100644 --- a/crates/solidity/outputs/npm/crate/src/generated/support/choice_helper.rs +++ b/crates/solidity/outputs/npm/crate/src/generated/support/choice_helper.rs @@ -107,7 +107,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, From 097ac2566db43c2824152093fdc7a235841b4e34 Mon Sep 17 00:00:00 2001 From: Igor Matuszewski Date: Mon, 4 Dec 2023 21:50:33 +0100 Subject: [PATCH 2/4] feat: Run `cargo doc` as part of the `infra check` To catch any broken links in the docs. --- crates/infra/cli/generated/infra.zsh-completions | 1 + crates/infra/cli/src/commands/check/mod.rs | 7 +++++++ crates/infra/utils/src/cargo/workspace.rs | 13 +++++++++++-- 3 files changed, 19 insertions(+), 2 deletions(-) diff --git a/crates/infra/cli/generated/infra.zsh-completions b/crates/infra/cli/generated/infra.zsh-completions index a68dae217f..2e3037d516 100644 --- a/crates/infra/cli/generated/infra.zsh-completions +++ b/crates/infra/cli/generated/infra.zsh-completions @@ -43,6 +43,7 @@ _arguments "${_arguments_options[@]}" \ '-h[Print help (see more with '\''--help'\'')]' \ '--help[Print help (see more with '\''--help'\'')]' \ '*::commands:((cargo\:"Run '\''cargo check'\'' for all crates, features, and targets" +rustdoc\:"Run \`cargo doc\` to generate Rustdoc documentation and check for any broken links" npm\:"Check NPM packages for any outdated codegen steps" mkdocs\:"Check mkdocs documentation for any build issues or broken links"))' \ && ret=0 diff --git a/crates/infra/cli/src/commands/check/mod.rs b/crates/infra/cli/src/commands/check/mod.rs index 77e08d9bb0..49fe304082 100644 --- a/crates/infra/cli/src/commands/check/mod.rs +++ b/crates/infra/cli/src/commands/check/mod.rs @@ -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,6 +40,7 @@ impl OrderedCommand for CheckCommand { match self { CheckCommand::Cargo => check_cargo(), + CheckCommand::Rustdoc => check_rustdoc(), CheckCommand::Npm => check_npm(), CheckCommand::Mkdocs => check_mkdocs(), } @@ -48,6 +51,10 @@ fn check_cargo() -> Result<()> { CargoWorkspace::get_command("check")?.run() } +fn check_rustdoc() -> Result<()> { + CargoWorkspace::get_command("doc")?.run() +} + fn check_npm() -> Result<()> { NapiCompiler::run(NapiProfile::Debug) } diff --git a/crates/infra/utils/src/cargo/workspace.rs b/crates/infra/utils/src/cargo/workspace.rs index b4174b839d..e1306d6b14 100644 --- a/crates/infra/utils/src/cargo/workspace.rs +++ b/crates/infra/utils/src/cargo/workspace.rs @@ -99,12 +99,21 @@ impl CargoWorkspace { } pub fn get_command(subcommand: impl AsRef) -> Result { + let subcommand = subcommand.as_ref(); + let mut command = Command::new("cargo") - .arg(subcommand.as_ref()) + .arg(subcommand) .flag("--all") - .flag("--all-targets") .flag("--all-features"); + if subcommand == "doc" { + // Rustdoc does not support '--all-targets' and it makes sense to only check default --lib/--bins anyway. + // Since this is primarily used to check our own documentation, skip documenting dependencies. + command = command.flag("--no-deps"); + } else { + command = command.flag("--all-targets"); + } + if GitHub::is_running_in_ci() { // Using `$RUSTFLAGS' or '--' overrides any rustflags from `.cargo/config.toml'. // Using this syntax instead, as it is concatenated with the existing flags: From d1a1b19bd8fc719806b4895a1c02ef37639a9e40 Mon Sep 17 00:00:00 2001 From: Igor Matuszewski Date: Tue, 5 Dec 2023 18:46:44 +0100 Subject: [PATCH 3/4] Deny Rustdoc warnings in CI --- crates/infra/utils/src/cargo/workspace.rs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/crates/infra/utils/src/cargo/workspace.rs b/crates/infra/utils/src/cargo/workspace.rs index e1306d6b14..2348f370c1 100644 --- a/crates/infra/utils/src/cargo/workspace.rs +++ b/crates/infra/utils/src/cargo/workspace.rs @@ -124,6 +124,15 @@ impl CargoWorkspace { rustflags = serde_json::to_string(&["--deny", "warnings"])?, ), ); + // Rustdoc requires specifying RUSTDOCFLAGS, instead: + // See . + command = command.property( + "--config", + format!( + "build.rustdocflags = {rustdocflags}", + rustdocflags = serde_json::to_string(&["--deny", "warnings"])?, + ), + ); } Ok(command) From 8aa5435c48838c345ea6d697fef100e4c0a425f3 Mon Sep 17 00:00:00 2001 From: Igor Matuszewski Date: Tue, 5 Dec 2023 18:56:21 +0100 Subject: [PATCH 4/4] Check documentation for private items as well --- .../src/internals/parse_input_tokens/mod.rs | 2 +- .../parser/runtime/src/support/choice_helper.rs | 12 ------------ .../parser/runtime/src/support/sequence_helper.rs | 12 ------------ crates/infra/cli/src/commands/check/mod.rs | 12 ++++++++++-- crates/infra/cli/src/commands/lint/mod.rs | 4 +++- crates/infra/utils/src/cargo/workspace.rs | 10 +--------- .../crate/src/generated/support/choice_helper.rs | 12 ------------ .../crate/src/generated/support/sequence_helper.rs | 12 ------------ .../npm/crate/src/generated/support/choice_helper.rs | 12 ------------ .../crate/src/generated/support/sequence_helper.rs | 12 ------------ 10 files changed, 15 insertions(+), 85 deletions(-) diff --git a/crates/codegen/language/definition/src/internals/parse_input_tokens/mod.rs b/crates/codegen/language/definition/src/internals/parse_input_tokens/mod.rs index b337f075c6..8f1620d601 100644 --- a/crates/codegen/language/definition/src/internals/parse_input_tokens/mod.rs +++ b/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') to modify the parsing logic, + /// Allows implementations (like `Option`) 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 { ParseHelpers::field(name, input, errors) diff --git a/crates/codegen/parser/runtime/src/support/choice_helper.rs b/crates/codegen/parser/runtime/src/support/choice_helper.rs index 4814471648..d9b3a7fb59 100644 --- a/crates/codegen/parser/runtime/src/support/choice_helper.rs +++ b/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, diff --git a/crates/codegen/parser/runtime/src/support/sequence_helper.rs b/crates/codegen/parser/runtime/src/support/sequence_helper.rs index ee16c74316..ac13d04891 100644 --- a/crates/codegen/parser/runtime/src/support/sequence_helper.rs +++ b/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 { match f(SequenceHelper::default()) { ControlFlow::Break(result) => result, diff --git a/crates/infra/cli/src/commands/check/mod.rs b/crates/infra/cli/src/commands/check/mod.rs index 49fe304082..b5d1d88568 100644 --- a/crates/infra/cli/src/commands/check/mod.rs +++ b/crates/infra/cli/src/commands/check/mod.rs @@ -48,11 +48,19 @@ impl OrderedCommand for CheckCommand { } 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")?.run() + CargoWorkspace::get_command("doc")? + .flag("--no-deps") + .flag("--document-private-items") + .flag("--lib") + .flag("--bins") + .flag("--examples") + .run() } fn check_npm() -> Result<()> { diff --git a/crates/infra/cli/src/commands/lint/mod.rs b/crates/infra/cli/src/commands/lint/mod.rs index 748752e8f1..fa7ad0a58f 100644 --- a/crates/infra/cli/src/commands/lint/mod.rs +++ b/crates/infra/cli/src/commands/lint/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<()> { diff --git a/crates/infra/utils/src/cargo/workspace.rs b/crates/infra/utils/src/cargo/workspace.rs index 2348f370c1..a00c53f5f0 100644 --- a/crates/infra/utils/src/cargo/workspace.rs +++ b/crates/infra/utils/src/cargo/workspace.rs @@ -103,17 +103,9 @@ impl CargoWorkspace { let mut command = Command::new("cargo") .arg(subcommand) - .flag("--all") + .flag("--workspace") .flag("--all-features"); - if subcommand == "doc" { - // Rustdoc does not support '--all-targets' and it makes sense to only check default --lib/--bins anyway. - // Since this is primarily used to check our own documentation, skip documenting dependencies. - command = command.flag("--no-deps"); - } else { - command = command.flag("--all-targets"); - } - if GitHub::is_running_in_ci() { // Using `$RUSTFLAGS' or '--' overrides any rustflags from `.cargo/config.toml'. // Using this syntax instead, as it is concatenated with the existing flags: diff --git a/crates/solidity/outputs/cargo/crate/src/generated/support/choice_helper.rs b/crates/solidity/outputs/cargo/crate/src/generated/support/choice_helper.rs index 8c254a7a6a..412d7b32fd 100644 --- a/crates/solidity/outputs/cargo/crate/src/generated/support/choice_helper.rs +++ b/crates/solidity/outputs/cargo/crate/src/generated/support/choice_helper.rs @@ -81,18 +81,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, diff --git a/crates/solidity/outputs/cargo/crate/src/generated/support/sequence_helper.rs b/crates/solidity/outputs/cargo/crate/src/generated/support/sequence_helper.rs index 28e933b0a4..decdee623f 100644 --- a/crates/solidity/outputs/cargo/crate/src/generated/support/sequence_helper.rs +++ b/crates/solidity/outputs/cargo/crate/src/generated/support/sequence_helper.rs @@ -171,18 +171,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 { match f(SequenceHelper::default()) { ControlFlow::Break(result) => result, diff --git a/crates/solidity/outputs/npm/crate/src/generated/support/choice_helper.rs b/crates/solidity/outputs/npm/crate/src/generated/support/choice_helper.rs index 8c254a7a6a..412d7b32fd 100644 --- a/crates/solidity/outputs/npm/crate/src/generated/support/choice_helper.rs +++ b/crates/solidity/outputs/npm/crate/src/generated/support/choice_helper.rs @@ -81,18 +81,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, diff --git a/crates/solidity/outputs/npm/crate/src/generated/support/sequence_helper.rs b/crates/solidity/outputs/npm/crate/src/generated/support/sequence_helper.rs index 28e933b0a4..decdee623f 100644 --- a/crates/solidity/outputs/npm/crate/src/generated/support/sequence_helper.rs +++ b/crates/solidity/outputs/npm/crate/src/generated/support/sequence_helper.rs @@ -171,18 +171,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 { match f(SequenceHelper::default()) { ControlFlow::Break(result) => result,