src/cli: improve docs

src/cli/command.rs

@@ -14,12 +14,18 @@ use super::getopts;
 use super::{CommandLineInterface, CliCommand, CliCommandMap, completion::*};
 use super::format::*;
 
+/// Schema definition for ``--output-format`` parameter.
+///
+/// - ``text``: command specific text format.
+/// - ``json``: JSON, single line.
+/// - ``json-pretty``: JSON, human readable.
+///
 pub const OUTPUT_FORMAT: Schema =
     StringSchema::new("Output format.")
     .format(&ApiStringFormat::Enum(&["text", "json", "json-pretty"]))
     .schema();
 
-pub fn handle_simple_command(
+fn handle_simple_command(
     _top_def: &CommandLineInterface,
     prefix: &str,
     cli_cmd: &CliCommand,
@@ -69,7 +75,7 @@ pub fn handle_simple_command(
     Ok(())
 }
 
-pub fn handle_nested_command(
+fn handle_nested_command(
     top_def: &CommandLineInterface,
     prefix: &str,
     def: &CliCommandMap,
@@ -172,11 +178,15 @@ fn set_help_context(def: Option<Arc<CommandLineInterface>>) {
     HELP_CONTEXT.with(|ctx| { *ctx.borrow_mut() = def; });
 }
 
-pub fn help_command_def() ->  CliCommand {
+pub(crate) fn help_command_def() ->  CliCommand {
     CliCommand::new(&API_METHOD_COMMAND_HELP)
         .arg_param(&["command"])
 }
 
+/// Handle command invocation.
+///
+/// This command gets the command line ``args`` and tries to invoke
+/// the corresponding API handler.
 pub fn handle_command(
     def: Arc<CommandLineInterface>,
     prefix: &str,
@@ -199,6 +209,18 @@ pub fn handle_command(
     result
 }
 
+/// Helper to get arguments and invoke the command.
+///
+/// This helper reads arguments with ``std::env::args()``. The first
+/// argument is assumed to be the program name, and is passed as ``prefix`` to
+/// ``handle_command()``.
+///
+/// This helper automatically add the help command, and two special
+/// sub-command:
+///
+/// - ``bashcomplete``: Output bash completions instead of running the command.
+/// - ``printdoc``: Output ReST documentation.
+///
 pub fn run_cli_command(def: CommandLineInterface) {
 
     let def = match def {

src/cli/completion.rs

@@ -189,6 +189,12 @@ fn get_nested_completion(
     }
 }
 
+/// Helper to generate bash completions.
+///
+/// This helper extracts the command line from environment variable
+/// set by ``bash``, namely ``COMP_LINE`` and ``COMP_POINT``. This is
+/// passed to ``get_completions()``. Returned values are printed to
+/// ``stdout``.
 pub fn print_bash_completion(def: &CommandLineInterface) {
 
     let comp_point: usize = match std::env::var("COMP_POINT") {
@@ -213,6 +219,7 @@ pub fn print_bash_completion(def: &CommandLineInterface) {
     }
 }
 
+/// Compute possible completions for a partial command
 pub fn get_completions(
     cmd_def: &CommandLineInterface,
     line: &str,

src/cli/format.rs

@@ -7,7 +7,7 @@ use proxmox::api::format::*;
 
 use super::{CommandLineInterface, CliCommand, CliCommandMap};
 
-/// Helper function to format and print result
+/// Helper function to format and print result.
 ///
 /// This is implemented for machine generatable formats 'json' and
 /// 'json-pretty'. The 'text' format needs to be handled somewhere
@@ -26,6 +26,7 @@ pub fn format_and_print_result(
     }
 }
 
+/// Helper to generate command usage text for simple commands.
 pub fn generate_usage_str(
     prefix: &str,
     cli_cmd: &CliCommand,
@@ -115,6 +116,7 @@ pub fn generate_usage_str(
     text
 }
 
+/// Print command usage for simple commands to ``stderr``.
 pub fn print_simple_usage_error(
     prefix: &str,
     cli_cmd: &CliCommand,
@@ -124,6 +126,7 @@ pub fn print_simple_usage_error(
     eprint!("Error: {}\nUsage: {}", err_msg, usage);
 }
 
+/// Print command usage for nested commands to ``stderr``.
 pub fn print_nested_usage_error(
     prefix: &str,
     def: &CliCommandMap,
@@ -133,6 +136,7 @@ pub fn print_nested_usage_error(
     eprintln!("Error: {}\n\nUsage:\n\n{}", err_msg, usage);
 }
 
+/// Helper to generate command usage text for nested commands.
 pub fn generate_nested_usage(
     prefix: &str,
     def: &CliCommandMap,
@@ -163,6 +167,7 @@ pub fn generate_nested_usage(
     usage
 }
 
+/// Print help text to ``stderr``.
 pub fn print_help(
     top_def: &CommandLineInterface,
     mut prefix: String,

src/cli/readline.rs

@@ -2,6 +2,11 @@ use std::sync::Arc;
 
 use super::*;
 
+/// Helper trait implementation for ``rustyline``.
+///
+/// This can be used to generate interactive commands using
+/// ``rustyline`` (readline implementation).
+///
 pub struct CliHelper {
     cmd_def: Arc<CommandLineInterface>,
 }