[MISC] docs update for parse-tree command

guard/src/commands/parse_tree.rs

@@ -14,18 +14,35 @@ const RULES_HELP: &str = "Provide a rules file";
 #[derive(Debug, Clone, Eq, PartialEq, Args)]
 #[clap(about=ABOUT)]
 #[clap(arg_required_else_help = true)]
+/// .
+/// The ParseTree command prints out the parse tree for a given rule file
 pub struct ParseTree {
-    #[arg(short, long, help = RULES_HELP)]
+    // the path to a rules file that a data file will have access to
+    // if set to false, will attempt to parse rules from stdin
+    // default None
+    #[arg(short, long, help=RULES_HELP)]
     pub(crate) rules: Option<String>,
-    #[arg(short, long, help = OUTPUT_HELP)]
+    #[arg(short, long, help=OUTPUT_HELP)]
+    // the path to a file a user wants to print the output to
+    // default None
     pub(crate) output: Option<String>,
+    // print output in json
+    // default false
     #[arg(short=PRINT_JSON.1, long=PRINT_JSON.0, help=PRINT_JSON_HELP)]
     pub(crate) print_json: bool,
+    // print output in yaml
+    // default true
     #[arg(short=PRINT_YAML.1, long=PRINT_YAML.0, help=PRINT_YAML_HELP)]
     pub(crate) print_yaml: bool,
 }
 
 impl Executable for ParseTree {
+    /// .
+    /// prints the parse tree for a given rule file
+    ///
+    /// This function will return an error if
+    /// - any of the specified paths do not exist
+    /// - parse errors occur in the rule file
     fn execute(&self, writer: &mut Writer, reader: &mut Reader) -> Result<i32> {
         let mut file: Box<dyn std::io::Read> = match &self.rules {
             Some(file) => Box::new(std::io::BufReader::new(File::open(file)?)),

guard/src/commands/test.rs

@@ -58,30 +58,30 @@ const VERBOSE_HELP: &str = "Verbose logging";
 /// The test command evaluates rules against data files to determine success or failure based on
 /// pre-defined expected outcomes
 pub struct Test {
-    // the path to a rules file that a data file will have access to
-    // default None
-    // conflicts with directory attribute
+    /// the path to a rules file that a data file will have access to
+    /// default None
+    /// conflicts with directory attribute
     #[arg(name="rules-file", short, long, help=RULES_HELP)]
     pub(crate) rules: Option<String>,
-    // the path to the test-data file
-    // default None
-    // conflicts with directory attribute
+    /// the path to the test-data file
+    /// default None
+    /// conflicts with directory attribute
     #[arg(name="test-data", short, long, help=TEST_DATA_HELP)]
     pub(crate) test_data: Option<String>,
-    // the path to the directory that includes rule files, and a subdirectory labeled tests that
-    // includes test-data files
-    // default None
-    // conflicts with rules, and test_data attributes
+    /// the path to the directory that includes rule files, and a subdirectory labeled tests that
+    /// includes test-data files
+    /// default None
+    /// conflicts with rules, and test_data attributes
     #[arg(name=DIRECTORY.0, short, long=DIRECTORY.0, help=DIRECTORY_HELP)]
     pub(crate) directory: Option<String>,
-    // Sort alphabetically inside a directory
-    // default false
-    // conflicts with last_modified attribute
+    /// Sort alphabetically inside a directory
+    /// default false
+    /// conflicts with last_modified attribute
     #[arg(short, long, help=ALPHABETICAL_HELP, conflicts_with=LAST_MODIFIED.0)]
     pub(crate) alphabetical: bool,
-    // Sort by last modified times within a directory
-    // default false
-    // conflicts with last_modified attribute
+    /// Sort by last modified times within a directory
+    /// default false
+    /// conflicts with last_modified attribute
     #[arg(name="last-modified", short=LAST_MODIFIED.1, long=LAST_MODIFIED.0, help=LAST_MODIFIED_HELP, conflicts_with=ALPHABETICAL.0)]
     pub(crate) last_modified: bool,
     /// Output verbose logging, conflicts with output_format when not using single-line-summary

guard/src/lib.rs

@@ -21,6 +21,8 @@ pub trait CommandBuilder<T: Executable> {
 }
 
 #[derive(Default, Debug)]
+/// .
+/// A builder to help construct the `ParseTree` command
 pub struct ParseTreeBuilder {
     rules: Option<String>,
     output: Option<String>,
@@ -29,11 +31,9 @@ pub struct ParseTreeBuilder {
 }
 
 impl CommandBuilder<ParseTree> for ParseTreeBuilder {
+    /// .
+    /// builds a parse tree command
     fn try_build(self) -> crate::rules::Result<ParseTree> {
-        if self.print_json && self.print_yaml {
-            return Err(Error::IllegalArguments(String::from("cannot construct a ParseTree command when both print_json and print_yaml are set to true")));
-        }
-
         let ParseTreeBuilder {
             rules,
             output,
@@ -51,24 +51,28 @@ impl CommandBuilder<ParseTree> for ParseTreeBuilder {
 }
 
 impl ParseTreeBuilder {
+    /// path to the rules file to be evaluated
     pub fn rules(mut self, rules: Option<String>) -> Self {
         self.rules = rules;
 
         self
     }
 
+    /// path to the output file where the parse tree will be printed to
     pub fn output(mut self, output: Option<String>) -> Self {
         self.output = output;
 
         self
     }
 
+    /// print parse tree in JSON format
     pub fn print_json(mut self, arg: bool) -> Self {
         self.print_json = arg;
 
         self
     }
 
+    /// print parse tree in YAML format
     pub fn print_yaml(mut self, arg: bool) -> Self {
         self.print_yaml = arg;
 
@@ -78,7 +82,7 @@ impl ParseTreeBuilder {
 
 #[derive(Debug)]
 /// .
-/// A builder to help construct the `Validate` command for
+/// A builder to help construct the `Validate` command
 pub struct ValidateBuilder {
     rules: Vec<String>,
     data: Vec<String>,
@@ -296,6 +300,8 @@ impl ValidateBuilder {
 }
 
 #[derive(Default, Debug)]
+/// .
+/// A builder to help construct the `Test` command
 pub struct TestBuilder {
     rules: Option<String>,
     test_data: Option<String>,