docs: improve rustdoc coverage for public APIs

Author: kalaninja

crates/cli/src/cli.rs

@@ -1,7 +1,10 @@
+//! Clap definitions for the Gitlane command-line interface.
+
 use std::path::PathBuf;
 
 use clap::{Args, Parser, Subcommand, ValueEnum};
 
+/// Top-level Gitlane CLI arguments.
 #[derive(Debug, Parser)]
 #[command(
     name = "gitlane",
@@ -10,93 +13,135 @@ use clap::{Args, Parser, Subcommand, ValueEnum};
     long_about = None
 )]
 pub struct Cli {
+    /// Project directory or nested path used to locate `.gitlane`.
     #[arg(long, global = true, value_name = "PATH")]
     pub project: Option<PathBuf>,
 
+    /// Command to execute.
     #[command(subcommand)]
     pub command: Command,
 }
 
+/// Supported top-level Gitlane commands.
 #[derive(Debug, Subcommand)]
 pub enum Command {
+    /// Initialize a new Gitlane project scaffold.
     Init(InitArgs),
+    /// Validate project configuration and data.
     Validate,
+    /// Manage issues.
     Issue {
+        /// Issue subcommand to execute.
         #[command(subcommand)]
         command: IssueCommand,
     },
+    /// Inspect workflow configuration.
     Workflow {
+        /// Workflow subcommand to execute.
         #[command(subcommand)]
         command: WorkflowCommand,
     },
+    /// Inspect labels.
     Label {
+        /// Label subcommand to execute.
         #[command(subcommand)]
         command: LabelCommand,
     },
 }
 
+/// Arguments for `gitlane init`.
 #[derive(Debug, Args)]
 pub struct InitArgs {
+    /// Project name to write into the generated config.
     #[arg(long)]
     pub name: Option<String>,
 
+    /// Optional project description for the generated config.
     #[arg(long)]
     pub description: Option<String>,
 
+    /// Optional homepage URL for the generated config.
     #[arg(long)]
     pub homepage: Option<String>,
 
+    /// Config file format to use for generated files.
     #[arg(long, value_enum)]
     pub format: Option<InitFormatArg>,
 }
 
+/// Supported values for `gitlane init --format`.
 #[derive(Clone, Copy, Debug, ValueEnum)]
 pub enum InitFormatArg {
+    /// Generate TOML config files.
     Toml,
+    /// Generate JSON config files.
     Json,
+    /// Generate YAML config files using `.yaml`.
     Yaml,
+    /// Generate YAML config files using `.yml`.
     Yml,
 }
 
+/// Supported `gitlane issue` subcommands.
 #[derive(Debug, Subcommand)]
 pub enum IssueCommand {
+    /// Create a new issue.
     Create,
+    /// List issues.
     List,
+    /// Show one issue by id.
     Show(IssueShowArgs),
+    /// Apply a workflow transition to an issue.
     Transition(IssueTransitionArgs),
 }
 
+/// Arguments for `gitlane issue show`.
 #[derive(Debug, Args)]
 pub struct IssueShowArgs {
+    /// Issue identifier to display.
     pub id: String,
 }
 
+/// Arguments for `gitlane issue transition`.
 #[derive(Debug, Args)]
 pub struct IssueTransitionArgs {
+    /// Issue identifier to transition.
     pub id: String,
+    /// Transition identifier to apply.
     pub transition_id: String,
 }
 
+/// Supported `gitlane workflow` subcommands.
 #[derive(Debug, Subcommand)]
 pub enum WorkflowCommand {
+    /// Show the full workflow configuration.
     Show,
+    /// List workflow states.
     States,
+    /// List transitions, optionally filtered by source state.
     Transitions(WorkflowTransitionsArgs),
 }
 
+/// Arguments for `gitlane workflow transitions`.
 #[derive(Debug, Args)]
 pub struct WorkflowTransitionsArgs {
+    /// Optional source state id to filter transitions.
     #[arg(long = "from", value_name = "STATE_ID")]
     pub from_state: Option<String>,
 }
 
+/// Supported `gitlane label` subcommands.
 #[derive(Debug, Subcommand)]
 pub enum LabelCommand {
+    /// List labels.
     List,
+    /// Show one label by id.
     Show(LabelShowArgs),
 }
 
+/// Arguments for `gitlane label show`.
 #[derive(Debug, Args)]
 pub struct LabelShowArgs {
+    /// Label identifier to display.
     pub id: String,
 }

crates/cli/src/main.rs

@@ -1,3 +1,5 @@
+//! Gitlane command-line entry point.
+
 mod cli;
 mod path;
 

crates/cli/src/path.rs

@@ -1,3 +1,5 @@
+//! Helpers for resolving the active Gitlane project directory.
+
 use std::{
     ffi::OsStr,
     path::{Path, PathBuf},
@@ -9,6 +11,7 @@ use gitlane::{
     paths::GITLANE_DIR,
 };
 
+/// Resolves the nearest `.gitlane` directory from `start_path` or its parents.
 pub fn resolve_project(start_path: &Path) -> anyhow::Result<PathBuf> {
     let start = start_path
         .canonicalize()

crates/core/src/config.rs

@@ -1,3 +1,5 @@
+//! Config file discovery and format helpers for Gitlane project data.
+
 use std::path::{Path, PathBuf};
 
 use thiserror::Error;
@@ -19,9 +21,13 @@ pub const ISSUES_WORKFLOW_CONFIG_STEM: &str = "workflow";
 /// Logical config file kinds supported by Gitlane.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ConfigKind {
+    /// Project metadata config stored at the project root.
     Project,
+    /// Issue tracker config stored under `.gitlane/issues`.
     Issues,
+    /// Issue labels config stored under `.gitlane/issues`.
     IssuesLabels,
+    /// Issue workflow config stored under `.gitlane/issues`.
     IssuesWorkflow,
 }
 
@@ -40,19 +46,26 @@ impl ConfigKind {
 /// File extensions accepted for config files.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ConfigFileExtension {
+    /// TOML config files.
     Toml,
+    /// JSON config files.
     Json,
+    /// YAML config files using the `.yaml` extension.
     Yaml,
+    /// YAML config files using the `.yml` extension.
     Yml,
 }
 
 /// Parser-specific errors for supported config formats.
 #[derive(Debug, Error)]
 pub enum ConfigParseError {
+    /// TOML parser error.
     #[error(transparent)]
     Toml(#[from] toml::de::Error),
+    /// JSON parser error.
     #[error(transparent)]
     Json(#[from] serde_json::Error),
+    /// YAML parser error.
     #[error(transparent)]
     Yaml(#[from] serde_yaml::Error),
 }
@@ -70,10 +83,13 @@ impl ConfigParseError {
 /// Serializer-specific errors for supported config formats.
 #[derive(Debug, Error)]
 pub enum ConfigSerializeError {
+    /// TOML serializer error.
     #[error(transparent)]
     Toml(#[from] toml_edit::ser::Error),
+    /// JSON serializer error.
     #[error(transparent)]
     Json(#[from] serde_json::Error),
+    /// YAML serializer error.
     #[error(transparent)]
     Yaml(#[from] serde_yaml::Error),
 }

crates/core/src/errors.rs

@@ -1,3 +1,5 @@
+//! Shared error types for Gitlane core operations.
+
 use std::path::{Path, PathBuf};
 
 use thiserror::Error;
@@ -14,44 +16,55 @@ use crate::{
 /// Top-level error type for Gitlane core operations.
 #[derive(Debug, Error)]
 pub enum GitlaneError {
+    /// The provided project name was empty or whitespace-only.
     #[error("project name must be a non-empty, non-whitespace string")]
     InvalidProjectName,
+    /// Initialization was attempted where a project config already exists.
     #[error("project already exists at `{path}`")]
     ProjectAlreadyExists { path: PathBuf },
+    /// A required logical config file was not found.
     #[error("missing supported {config_name} config file in `{directory}`")]
     MissingConfigFile {
         config_name: &'static str,
         directory: PathBuf,
     },
+    /// More than one supported file exists for the same logical config.
     #[error("found multiple supported {config_name} config files: {paths:?}")]
     AmbiguousConfigFiles {
         config_name: &'static str,
         paths: Vec<PathBuf>,
     },
+    /// A config file path did not use a supported extension.
     #[error("unsupported config format for `{path}`; expected .toml, .json, .yaml, or .yml")]
     UnsupportedConfigFormat { path: PathBuf },
+    /// A config file parsed but failed semantic validation.
     #[error("invalid config in `{path}`: {message}")]
     InvalidConfig { path: PathBuf, message: String },
+    /// Parsing a config file failed.
     #[error("failed to parse `{path}` as {format}", format = .source.format_name())]
     ParseConfig {
         path: PathBuf,
         #[source]
         source: ConfigParseError,
     },
+    /// Serializing a config file failed.
     #[error("failed to serialize `{path}` as {format}", format = .source.format_name())]
     SerializeConfig {
         path: PathBuf,
         #[source]
         source: ConfigSerializeError,
     },
+    /// Issue front matter parsed but failed semantic validation.
     #[error("invalid front matter in `{path}`: {message}")]
     InvalidFrontmatter { path: PathBuf, message: String },
+    /// Parsing issue front matter failed.
     #[error("failed to parse front matter in `{path}` as {format}", format = .source.format_name())]
     ParseFrontmatter {
         path: PathBuf,
         #[source]
         source: FrontmatterParseError,
     },
+    /// Serializing issue front matter failed.
     #[error(
         "failed to serialize front matter in `{path}` as {format}",
         format = .source.format_name()
@@ -61,8 +74,10 @@ pub enum GitlaneError {
         #[source]
         source: FrontmatterSerializeError,
     },
+    /// Parsed issue metadata failed semantic validation.
     #[error("invalid issue in `{path}`: {message}")]
     InvalidIssue { path: PathBuf, message: String },
+    /// A filesystem operation failed.
     #[error(transparent)]
     Filesystem(#[from] FsError),
 }

crates/core/src/frontmatter.rs

@@ -14,12 +14,16 @@ pub(crate) const JSON_OBJECT_END: char = '}';
 /// Parser-specific errors for supported front matter formats.
 #[derive(Debug, Error)]
 pub enum FrontmatterParseError {
+    /// TOML front matter parser error.
     #[error(transparent)]
     Toml(#[from] toml::de::Error),
+    /// TOML document parser error used for editable TOML front matter.
     #[error(transparent)]
     TomlDocument(#[from] toml_edit::TomlError),
+    /// JSON front matter parser error.
     #[error(transparent)]
     Json(#[from] serde_json::Error),
+    /// YAML front matter parser error.
     #[error(transparent)]
     Yaml(#[from] serde_yaml::Error),
 }
@@ -38,10 +42,13 @@ impl FrontmatterParseError {
 /// Serializer-specific errors for supported front matter formats.
 #[derive(Debug, Error)]
 pub enum FrontmatterSerializeError {
+    /// Timestamp formatting error while rendering front matter.
     #[error(transparent)]
     TimeFormat(#[from] time::error::Format),
+    /// JSON front matter serializer error.
     #[error(transparent)]
     Json(#[from] serde_json::Error),
+    /// YAML front matter serializer error.
     #[error(transparent)]
     Yaml(#[from] serde_yaml::Error),
 }
@@ -80,10 +87,14 @@ pub(crate) enum FrontmatterError {
     Parse(#[from] FrontmatterParseError),
 }
 
+/// Supported serialized front matter formats for issue documents.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum FrontmatterFormat {
+    /// TOML front matter delimited by `+++` fences.
     Toml,
+    /// JSON front matter stored as a top-level object.
     Json,
+    /// YAML front matter delimited by `---` fences.
     Yaml,
 }
 

crates/core/src/issues/config/mod.rs

@@ -1,3 +1,5 @@
+//! Validated issue tracker config types and rules.
+
 use std::{
     collections::{BTreeMap, HashSet},
     path::Path,

crates/core/src/issues/issue/mod.rs

@@ -1,3 +1,5 @@
+//! Typed issue document parsing, validation, and persistence.
+
 use std::{collections::HashSet, path::Path};
 
 use thiserror::Error;

crates/core/src/issues/labels/mod.rs

@@ -1,3 +1,5 @@
+//! Validated issue label config types and rules.
+
 use std::{collections::BTreeMap, path::Path};
 
 use crate::{

crates/core/src/issues/templates.rs

@@ -1,3 +1,5 @@
+//! Built-in issue template scaffolding helpers.
+
 use crate::config::ConfigFileExtension;
 use crate::frontmatter::{JSON_OBJECT_END, JSON_OBJECT_START, TOML_FENCE, YAML_FENCE};