doc,comment: added the descriptions for help printing. (#30)

Author: sttk

README.md

@@ -11,7 +11,7 @@ This library provides the following functionalities:
 - Supports parsing with option configurations.
 - Supports parsing with option configurations made from struct fields and attributes, and setting the option values to them.
 - Is able to parse command line arguments including sub commands. *(To be added)*
-- Generates help text from option configurations. *(To be added)*
+- Generates help text from option configurations.
 
 ## Install
 
@@ -123,6 +123,8 @@ The ownership of the vector of option configurations which is passed as an argum
 is moved to this method and set to the public field `cfgs` of `Cmd` instance.
 If you want to access the option configurations after parsing, get them from this field.
 
+In addition,the help printing for an array of `OptCfg` is generated with `Help`.
+
 ```
 use cliargs::{Cmd, OptCfg};
 use cliargs::OptCfgParam::{names, has_arg, defaults, validator, desc, arg_in_help};
@@ -155,6 +157,18 @@ match cmd.parse_with(opt_cfgs) {
     Err(InvalidOption::OptionArgIsInvalid { option, opt_arg, details, .. }) => { /* ... */ },
     Err(err) => panic!("Invalid option: {}", err.option()),
 }
+
+let opt_cfgs = cmd.opt_cfgs();
+
+let mut help = Help::new();
+help.add_text("This is the usage description.".to_string());
+help.add_opts_with_margins(opt_cfgs, 2, 0);
+help.print();
+
+// (stdout)
+// This is the usage description.
+//   --foo-bar, -f    This is description of foo-bar.
+//   --bar, -z <num>  This is description of baz.
 ```
 
 ### Parse for a OptStore struct
@@ -222,7 +236,17 @@ match cmd.parse_for(&mut my_options) {
     Err(err) => panic!("Invalid option: {}", err.option()),
 }
 
-let opt_cfgs = &cmd.cfgs;
+let opt_cfgs = cmd.opt_cfgs();
+
+let mut help = Help::new();
+help.add_text("This is the usage description.".to_string());
+help.add_opts_with_margins(opt_cfgs, 2, 0);
+help.print();
+
+// (stdout)
+// This is the usage description.
+//   -f, --foo-bar  This is description of foo_bar.
+//   -z, --baz <s>  This is description of baz.
 ```
 
 ## Supporting Rust versions
@@ -234,7 +258,7 @@ This crate supports Rust 1.74.1 or later.
 Fetching index
 Determining the Minimum Supported Rust Version (MSRV) for toolchain x86_64-apple-darwin
 Using check command cargo check
-   Finished The MSRV is: 1.74.1   █████████████████████████████████████████████████████████ 00:00:04
+   Finished The MSRV is: 1.74.1   ████████████████████████████████████████████ 00:00:04
 ```
 
 

src/help/mod.rs

@@ -70,12 +70,7 @@ impl Help {
     /// The margins of this help text block generated by this instance equals the sum of them
     /// specified as parameters of this method and them which specified at a constructor.
     /// The indent width of this help text block is set to *auto indentation*.
-    pub fn add_text_with_margins(
-        &mut self,
-        text: String,
-        margin_left: usize,
-        margin_right: usize,
-    ) {
+    pub fn add_text_with_margins(&mut self, text: String, margin_left: usize, margin_right: usize) {
         self.add_text_with_indent_and_margins(text, 0, margin_left, margin_right)
     }
 

src/lib.rs

@@ -14,6 +14,7 @@
 //! - Supports parsing with option configurations.
 //! - Supports parsing with option configurations made from struct fields and attributes, and
 //!   setting the option values to them.
+//! - Generates help text from option configurations.
 //!
 //! [posix]: https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html#Argument-Syntax
 //! [gnu]: https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html
@@ -145,11 +146,14 @@
 //! This crate provides the validator `cliargs::validators::validate_number<T>`
 //! which validates whether an option argument is valid format as a number.
 //!
+//! In addition,the help printing for an array of [OptCfg] is generated with [Help].
+//!
 //! ```
 //! use cliargs::{Cmd, OptCfg};
 //! use cliargs::OptCfgParam::{names, has_arg, defaults, validator, desc, arg_in_help};
 //! use cliargs::validators::validate_number;
 //! use cliargs::errors::InvalidOption;
+//! use cliargs::Help;
 //!
 //! let mut cmd = Cmd::with_strings(vec![ /* ... */ ]);
 //! let opt_cfgs = vec![
@@ -183,6 +187,18 @@
 //!     Err(InvalidOption::OptionArgIsInvalid { option, opt_arg, details, .. }) => { /* ... */ },
 //!     Err(err) => panic!("Invalid option: {}", err.option()),
 //! }
+//!
+//! let opt_cfgs = cmd.opt_cfgs();
+//!
+//! let mut help = Help::new();
+//! help.add_text("This is the usage description.".to_string());
+//! help.add_opts_with_margins(opt_cfgs, 2, 0);
+//! help.print();
+//!
+//! // (stdout)
+//! // This is the usage description.
+//! //   --foo-bar, -f    This is description of foo-bar.
+//! //   --bar, -z <num>  This is description of baz.
 //! ```
 //!
 //! ## Parse for a OptStore struct
@@ -220,6 +236,45 @@
 //! it doesn't represent an array which contains only one empty string.
 //! If you want to specify an array which contains only one emtpy string, write nothing after `=` symbol, like
 //! `#[opt(cfg="=")]`.
+//!
+//! ```
+//! use cliargs::Cmd;
+//! use cliargs::errors::InvalidOption;
+//! use cliargs::Help;
+//!
+//! #[derive(cliargs::OptStore)]
+//! struct MyOptions {
+//!     #[opt(cfg = "f,foo-bar", desc="The description of foo_bar.")]
+//!     foo_bar: bool,
+//!     #[opt(cfg = "b,baz", desc="The description of baz.", arg="<s>")]
+//!     baz: String,
+//! }
+//! let mut my_options = MyOptions::with_defaults();
+//!
+//! let mut cmd = Cmd::with_strings(vec![ /* ... */ ]);
+//! match cmd.parse_for(&mut my_options) {
+//!     Ok(_) => { /* ... */ },
+//!     Err(InvalidOption::OptionContainsInvalidChar { option }) => { /* ... */ },
+//!     Err(InvalidOption::UnconfiguredOption { option }) => { /* ... */ },
+//!     Err(InvalidOption::OptionNeedsArg { option, .. }) => { /* ... */ },
+//!     Err(InvalidOption::OptionTakesNoArg { option, .. }) => { /* ... */ },
+//!     Err(InvalidOption::OptionIsNotArray { option, .. }) => { /* ... */ },
+//!     Err(InvalidOption::OptionArgIsInvalid { option, opt_arg, details, .. }) => { /* ... */ },
+//!     Err(err) => panic!("Invalid option: {}", err.option()),
+//! }
+//!
+//! let opt_cfgs = cmd.opt_cfgs();
+//!
+//! let mut help = Help::new();
+//! help.add_text("This is the usage description.".to_string());
+//! help.add_opts_with_margins(opt_cfgs, 2, 0);
+//! help.print();
+//!
+//! // (stdout)
+//! // This is the usage description.
+//! //   -f, --foo-bar  This is description of foo_bar.
+//! //   -z, --baz <s>  This is description of baz.
+//! ```
 
 /// Enums for errors that can occur when parsing command line arguments.
 pub mod errors;