From 274fbbf097ef263cfd46615dc4587681dd1392e3 Mon Sep 17 00:00:00 2001 From: a dinosaur Date: Sun, 2 Nov 2025 22:22:42 +1100 Subject: [PATCH] Fix glaring errors in docstrings --- src/argparse.rs | 18 +++++++++--------- src/option.rs | 22 +++++++++++----------- src/options.rs | 4 ++-- src/std.rs | 26 +++++++++++++------------- 4 files changed, 35 insertions(+), 35 deletions(-) diff --git a/src/argparse.rs b/src/argparse.rs index 569d718..6b1ed6c 100644 --- a/src/argparse.rs +++ b/src/argparse.rs @@ -6,15 +6,15 @@ /// Enum describing the result of parsing arguments, and how the program should behave. #[derive(Debug)] pub enum ParseResult { - /// Parsing succeeded and program execution should continue + /// Parsing succeeded and program execution should continue. ContinueSuccess, - /// Parsing succeeded and program should exit with success (eg; std::process::ExitCode::SUCCESS) + /// Parsing succeeded and program should exit with success (eg; [std::process::ExitCode::SUCCESS]). ExitSuccess, - /// There was an error while parsing and program should exit with failure (eg; std::process::ExitCode::FAILURE) + /// There was an error while parsing and program should exit with failure (eg; [std::process::ExitCode::FAILURE]). ExitError, } -/// Execution control for the parser handler +/// Execution control for parser handlers. pub enum ParseControl { /// Continue parsing arguments Continue, @@ -24,7 +24,7 @@ pub enum ParseControl { Quit, } -/// Result type used by the handler passed to the parser +/// Result type used by the handler passed to the parser. type HandlerResult<'a, T> = core::result::Result>; #[derive(Debug)] @@ -69,7 +69,7 @@ impl core::fmt::Display for ParseError<'_> { } } -/// Convenience coercion for dealing with integer parsing errors +/// Convenience coercion for dealing with integer parsing errors. impl From for ParseError<'_> { fn from(err: core::num::ParseIntError) -> Self { use core::num::IntErrorKind; @@ -83,7 +83,7 @@ impl From for ParseError<'_> { } } -/// Convenience coercion for dealing with floating-point parsing errors +/// Convenience coercion for dealing with floating-point parsing errors. impl From for ParseError<'_> { fn from(_err: core::num::ParseFloatError) -> Self { // HACK: The empty option & argument fields will be fixed up by the parser @@ -94,7 +94,7 @@ impl From for ParseError<'_> { impl core::error::Error for ParseError<'_> {} -/// Internal state tracked by the parser +/// Internal state tracked by the parser. struct ParserState { positional_index: usize, expects_arg: Option<(&'static str, &'static Opt)>, @@ -112,7 +112,7 @@ impl Default for ParserState { } impl Opts { - /// Parse an iterator of strings as arguments + /// Parses an iterator of strings as argument tokens. pub fn parse<'a, S: AsRef + 'a, I: Iterator>(&self, program_name: &str, args: I, mut handler: impl FnMut(&str, &ID, &Opt, &str, &str) -> HandlerResult<'a, ParseControl>, error: impl FnOnce(&str, ParseError), diff --git a/src/option.rs b/src/option.rs index ff660f2..710a7ba 100644 --- a/src/option.rs +++ b/src/option.rs @@ -16,7 +16,7 @@ enum OptIdentifier { Multi(&'static[&'static str]), } -/// Represents an option argument or positional argument to be parsed +/// Represents an option argument or positional argument to be parsed. #[derive(Debug)] pub struct Opt { id: ID, @@ -48,20 +48,20 @@ impl Opt { Self { id, names, value_name, help_string: None, r#type, flags: OptFlag::NONE } } - /// A positional argument that is parsed sequentially without being invoked by an option flag + /// A positional argument that is parsed sequentially without being invoked by an option flag. pub const fn positional(id: ID, name: &'static str) -> Self { Self::new(id, OptIdentifier::Single(name), None, OptType::Positional) } - /// A flag-type option that serves as the interface's help flag + /// A flag-type option that serves as the interface's help flag. pub const fn help_flag(id: ID, names: &'static[&'static str]) -> Self { Self::new(id, OptIdentifier::Multi(names), None, OptType::Flag) .with_help_flag() } - /// A flag-type option, takes no value + /// A flag-type option, takes no value. pub const fn flag(id: ID, names: &'static[&'static str]) -> Self { Self::new(id, OptIdentifier::Multi(names), None, OptType::Flag) } - /// An option argument that takes a value + /// An option argument that takes a value. pub const fn value(id: ID, names: &'static[&'static str], value_name: &'static str) -> Self { Self::new(id, OptIdentifier::Multi(names), Some(value_name), OptType::Value) } @@ -93,7 +93,7 @@ impl Opt { } impl Opt { - /// Get the first name of the option + /// Get the first name of the option. const fn first_name(&self) -> &str { match self.names { OptIdentifier::Single(name) => name, @@ -101,7 +101,7 @@ impl Opt { } } - /// Get the first long option name, if one exists + /// Get the first long option name, if one exists. const fn first_long_name(&self) -> Option<&'static str> { match self.names { OptIdentifier::Single(name) => if name.len() >= 3 { Some(name) } else { None }, @@ -119,7 +119,7 @@ impl Opt { } } - /// Get the first short option name, if one exists + /// Get the first short option name, if one exists. const fn first_short_name(&self) -> Option<&'static str> { const fn predicate(name: &str) -> bool { let mut chars = const_utf8::CharIterator::from(name); @@ -148,7 +148,7 @@ impl Opt { } } - /// Get the first applicable short option's flag character, if one exists + /// Get the first applicable short option's flag character, if one exists. const fn first_short_name_char(&self) -> Option { const fn predicate(name: &str) -> Option { let mut chars = const_utf8::CharIterator::from(name); @@ -163,7 +163,7 @@ impl Opt { } match self.names { OptIdentifier::Single(name) => predicate(&name), - // Can be replaced with `find_map` once iterators are const fn + // Can be replaced with `find_map` once iterators are const fn. OptIdentifier::Multi(names) => { let mut i = 0; while i < names.len() { @@ -177,7 +177,7 @@ impl Opt { } } - /// Search for a matching name in the option, offset allows to skip the first characters in the comparison + /// Search for a matching name in the option, offset allows to skip the first `n = offset` characters in the comparison. fn match_name(&self, string: &str, offset: usize) -> Option<&'static str> { match self.names { OptIdentifier::Single(name) => diff --git a/src/options.rs b/src/options.rs index e737fab..fa866cb 100644 --- a/src/options.rs +++ b/src/options.rs @@ -3,7 +3,7 @@ * SPDX-License-Identifier: MIT */ -/// Static structure that contains instructions for parsing command-line arguments +/// Static structure that contains instructions for parsing command-line arguments. pub struct Opts { /// List of options options: &'static[Opt], @@ -19,7 +19,7 @@ type RequiredParamsBitSet = ordered_bitset::OrderedBitSet; pub const MAX_REQUIRED_OPTIONS: usize = RequiredParamsBitSet::CAPACITY; impl Opts { - /// Build argument parser options with the default flag character of '-' + /// Build argument parser options with the default flag character of '-'. pub const fn new(options: &'static[Opt]) -> Self { // Validate passed options let mut opt_idx = 0; diff --git a/src/std.rs b/src/std.rs index db848ba..8e39e10 100644 --- a/src/std.rs +++ b/src/std.rs @@ -13,34 +13,34 @@ use std::string::String; use std::{env, eprintln, println}; impl Opts { - /// Wrapper around `jaarg::parse` that gathers arguments from the command line and prints errors to stderr. + /// Wrapper around [Opts::parse] that gathers arguments from the command line and prints errors to stderr. /// The errors are formatted in a standard user-friendly format. /// - /// Requires features = [std] + /// Requires `features = [std]`. pub fn parse_easy<'a>(&self, handler: impl FnMut(&str, &ID, &Opt, &str, &str) -> HandlerResult<'a, ParseControl> ) -> ParseResult { let (program_name, argv) = Self::easy_args(); self.parse(&program_name, argv, handler, |name, e| self.easy_error(name, e)) } - /// Prints full help text for the options using the standard full + /// Prints full help text for the options using the standard full. /// - /// Requires features = [std] + /// Requires `features = [std]`. pub fn print_full_help(&self, program_name: &str) { self.print_help::>(program_name); } - /// Print help text to stdout using the provided help writer + /// Print help text to stdout using the provided help writer. /// - /// Requires features = [std] + /// Requires `features = [std]`. pub fn print_help<'a, W: HelpWriter<'a, ID>>(&'a self, program_name: &'a str) { let ctx = HelpWriterContext { options: self, program_name }; println!("{}", W::new(ctx)); } - /// Print help text to stderr using the provided help writer + /// Print help text to stderr using the provided help writer. /// - /// Requires features = [std] + /// Requires `features = [std]`. pub fn eprint_help<'a, W: HelpWriter<'a, ID>>(&'a self, program_name: &'a str) { let ctx = HelpWriterContext { options: self, program_name }; eprintln!("{}", W::new(ctx)); @@ -63,16 +63,16 @@ impl Opts { } } -/// The result of parsing commands using `jaarg::Opts::parse_map`. +/// The result of parsing commands with [Opts::parse_map]. pub enum ParseMapResult { Map(BTreeMap<&'static str, String>), Exit(std::process::ExitCode), } impl Opts<&'static str> { - /// Parse an iterator of strings as arguments and return the results in a BTreeMap. + /// Parse an iterator of strings as arguments and return the results in a [BTreeMap]. /// - /// Requires features = [std] + /// Requires `features = [std]`. pub fn parse_map<'a, S: AsRef + 'a, I: Iterator>(&self, program_name: &str, args: I, help: impl Fn(&str), error: impl FnOnce(&str, ParseError) ) -> ParseMapResult { @@ -92,10 +92,10 @@ impl Opts<&'static str> { } } - /// Parse arguments from the command line and return the results in a BTreeMap. + /// Parse arguments from the command line and return the results in a [BTreeMap]. /// Help and errors are formatted in a standard user-friendly format. /// - /// Requires features = [std] + /// Requires `features = [std]`. pub fn parse_map_easy(&self) -> ParseMapResult { let (program_name, argv) = Self::easy_args(); self.parse_map(&program_name, argv,