Fix private intradoc links

- setup CI to check private intradoc links
- make `cargo.doc` Makefile command to generate private item docs by default

Author: tyranron

.github/workflows/ci.yml

@@ -115,7 +115,7 @@ jobs:
           profile: minimal
           toolchain: stable
 
-      - run: make cargo.doc open=no
+      - run: make cargo.doc private=yes open=no
 
 
 

Makefile

@@ -39,14 +39,16 @@ test: test.cargo test.book
 # Generate crates documentation from Rust sources.
 #
 # Usage:
-#	make cargo.doc [crate=<crate-name>] [open=(yes|no)] [clean=(no|yes)]
+#	make cargo.doc [crate=<crate-name>] [private=(yes|no)]
+#	               [open=(yes|no)] [clean=(no|yes)]
 
 cargo.doc:
 ifeq ($(clean),yes)
 	@rm -rf target/doc/
 endif
 	cargo +stable doc $(if $(call eq,$(crate),),--workspace,-p $(crate)) \
 		--all-features \
+		$(if $(call eq,$(private),no),,--document-private-items) \
 		$(if $(call eq,$(open),no),,--open)
 
 

codegen/src/attribute.rs

@@ -212,8 +212,8 @@ impl Step {
         })
     }
 
-    /// Composes name of the [`WorldInventory`] method to wire this [`Step`]
-    /// with.
+    /// Composes a name of the `cucumber::codegen::WorldInventory` method to
+    /// wire this [`Step`] with.
     fn constructor_method(&self) -> syn::Ident {
         format_ident!("new_{}", self.attr_name)
     }
@@ -224,6 +224,7 @@ impl Step {
     /// Function's argument type have to implement [`FromStr`].
     ///
     /// [`FromStr`]: std::str::FromStr
+    /// [`syn::Ident`]: struct@syn::Ident
     fn arg_ident_and_parse_code<'a>(
         &self,
         arg: &'a syn::FnArg,
@@ -302,7 +303,9 @@ enum AttributeArgument {
 }
 
 impl AttributeArgument {
-    /// Returns [`syn::LitStr`] to construct a [`Regex`] with.
+    /// Returns a [`syn::LitStr`] to construct a [`Regex`] with.
+    ///
+    /// [`syn::LitStr`]: struct@syn::LitStr
     fn regex_literal(&self) -> syn::LitStr {
         match self {
             Self::Regex(l) => l.clone(),
@@ -431,6 +434,8 @@ fn remove_attr(attr_arg: &str, arg: &mut syn::FnArg) -> Option<syn::Attribute> {
 }
 
 /// Parses [`syn::Ident`] and [`syn::Type`] from the given [`syn::FnArg`].
+///
+/// [`syn::Ident`]: struct@syn::Ident
 fn parse_fn_arg(arg: &syn::FnArg) -> syn::Result<(&syn::Ident, &syn::Type)> {
     let arg = match arg {
         syn::FnArg::Typed(t) => t,
@@ -476,7 +481,7 @@ fn find_first_slice(sig: &syn::Signature) -> Option<&syn::TypePath> {
     })
 }
 
-/// Parses [`cucumber::World`] from arguments of the function signature.
+/// Parses `cucumber::World` from arguments of the function signature.
 fn parse_world_from_args(sig: &syn::Signature) -> syn::Result<&syn::TypePath> {
     sig.inputs
         .first()
@@ -506,6 +511,9 @@ fn parse_world_from_args(sig: &syn::Signature) -> syn::Result<&syn::TypePath> {
 }
 
 /// Converts [`syn::Lit`] to [`syn::LitStr`] if possible.
+///
+/// [`syn::Lit`]: enum@syn::Lit
+/// [`syn::LitStr`]: struct@syn::LitStr
 fn to_string_literal(l: syn::Lit) -> syn::Result<syn::LitStr> {
     match l {
         syn::Lit::Str(str) => Ok(str),

codegen/src/derive.rs

@@ -36,6 +36,8 @@ pub(crate) fn world_init(
 }
 
 /// Generates [`syn::Ident`]s of generic types for private trait impl.
+///
+/// [`syn::Ident`]: struct@syn::Ident
 fn step_types(steps: &[&str]) -> Vec<syn::Ident> {
     steps
         .iter()

src/feature.rs

@@ -115,7 +115,7 @@ impl Ext for gherkin::Feature {
 ///
 /// See [`ExpandExamplesError`] for details.
 ///
-/// [`Examples`]: gherkin::Example
+/// [`Examples`]: gherkin::Examples
 /// [`Scenario`]: gherkin::Scenario
 fn expand_scenario(
     scenario: gherkin::Scenario,

src/runner/basic.rs

@@ -1087,6 +1087,8 @@ struct Features {
     scenarios: Arc<Mutex<Scenarios>>,
 
     /// Indicates whether all parsed [`Feature`]s are sorted and stored.
+    ///
+    /// [`Feature`]: gherkin::Feature
     finished: Arc<AtomicBool>,
 }
 

src/step.rs

@@ -169,7 +169,7 @@ pub struct Context {
     pub matches: Vec<String>,
 }
 
-/// [`Regex`] wrapper to store inside a [`LinkedHashMap`].
+/// [`Regex`] wrapper to store it as a key of a [`HashMap`].
 #[derive(Clone, Debug)]
 struct HashableRegex(Regex);
 

src/writer/basic.rs

@@ -117,13 +117,14 @@ impl Basic {
         }
     }
 
-    /// Outputs [error] encountered while parsing some [`Feature`].
+    /// Outputs the parsing `error` encountered while parsing some [`Feature`].
     ///
-    /// [error]: event::Cucumber::ParsingError
     /// [`Feature`]: gherkin::Feature
-    fn parsing_failed(&self, err: impl Display) {
-        self.write_line(&self.styles.err(format!("Failed to parse: {}", err)))
-            .unwrap();
+    fn parsing_failed(&self, error: impl Display) {
+        self.write_line(
+            &self.styles.err(format!("Failed to parse: {}", error)),
+        )
+        .unwrap();
     }
 
     /// Outputs [started] [`Feature`] to STDOUT.
@@ -145,6 +146,7 @@ impl Basic {
     /// [finished]: event::Rule::Finished
     /// [scenario]: event::Rule::Scenario
     /// [started]: event::Rule::Started
+    /// [`Rule`]: gherkin::Rule
     fn rule<W: Debug>(
         &mut self,
         feat: &gherkin::Feature,
@@ -184,7 +186,7 @@ impl Basic {
 
     /// Outputs [`Scenario`] [started]/[background]/[step] event to STDOUT.
     ///
-    /// [background]: event::Background
+    /// [background]: event::Scenario::Background
     /// [started]: event::Scenario::Started
     /// [step]: event::Step
     /// [`Scenario`]: gherkin::Scenario
@@ -306,7 +308,7 @@ impl Basic {
     /// This [`Step`] is printed only if terminal is present and gets
     /// overwritten by later [passed]/[skipped]/[failed] events.
     ///
-    /// [started]: event::Step::Started
+    /// [failed]: event::Step::Failed
     /// [passed]: event::Step::Passed
     /// [skipped]: event::Step::Skipped
     /// [started]: event::Step::Started
@@ -489,7 +491,7 @@ impl Basic {
     /// This [`Step`] is printed only if terminal is present and gets
     /// overwritten by later [passed]/[skipped]/[failed] events.
     ///
-    /// [started]: event::Step::Started
+    /// [failed]: event::Step::Failed
     /// [passed]: event::Step::Passed
     /// [skipped]: event::Step::Skipped
     /// [started]: event::Step::Started