add with_about for CLI commands (#2741)

* add with_about for echo, server, and auth

* update for feedback

* finish (most) remaining command documentation

* update comments after additional clarification

* add expanded_api descriptions

* add comments for action_api

* add comments for remaining apis

* add comment for package-rebuild

* fix build errors

* missed one with_about

* add context to git-info subcommands

* remove context from git-info subcommands

* Make git-info from_fns generic over context

* make version::git_info generic over the context

* try removing generics from subcommand and version::git_info

* try adding a closure with context

* Updates for reviewer feedback

core/startos/src/registry/admin.rs

@@ -18,14 +18,23 @@ use crate::util::serde::{display_serializable, HandlerExtSerde, WithIoFormat};
 
 pub fn admin_api<C: Context>() -> ParentHandler<C> {
     ParentHandler::new()
-        .subcommand("signer", signers_api::<C>())
+        .subcommand(
+            "signer",
+            signers_api::<C>().with_about("Commands to add or list signers"),
+        )
         .subcommand("add", from_fn_async(add_admin).no_cli())
-        .subcommand("add", from_fn_async(cli_add_admin).no_display())
+        .subcommand(
+            "add",
+            from_fn_async(cli_add_admin)
+                .no_display()
+                .with_about("Add admin signer"),
+        )
         .subcommand(
             "list",
             from_fn_async(list_admins)
                 .with_display_serializable()
                 .with_custom_display_fn(|handle, result| Ok(display_signers(handle.params, result)))
+                .with_about("List admin signers")
                 .with_call_remote::<CliContext>(),
         )
 }
@@ -38,6 +47,7 @@ fn signers_api<C: Context>() -> ParentHandler<C> {
                 .with_metadata("admin", Value::Bool(true))
                 .with_display_serializable()
                 .with_custom_display_fn(|handle, result| Ok(display_signers(handle.params, result)))
+                .with_about("List signers")
                 .with_call_remote::<CliContext>(),
         )
         .subcommand(
@@ -46,7 +56,10 @@ fn signers_api<C: Context>() -> ParentHandler<C> {
                 .with_metadata("admin", Value::Bool(true))
                 .no_cli(),
         )
-        .subcommand("add", from_fn_async(cli_add_signer))
+        .subcommand(
+            "add",
+            from_fn_async(cli_add_signer).with_about("Add signer"),
+        )
 }
 
 impl Model<BTreeMap<Guid, SignerInfo>> {

core/startos/src/registry/db.rs

@@ -18,14 +18,24 @@ use crate::util::serde::{apply_expr, HandlerExtSerde};
 
 pub fn db_api<C: Context>() -> ParentHandler<C> {
     ParentHandler::new()
-        .subcommand("dump", from_fn_async(cli_dump).with_display_serializable())
+        .subcommand(
+            "dump",
+            from_fn_async(cli_dump)
+                .with_display_serializable()
+                .with_about("Filter/query db to display tables and records"),
+        )
         .subcommand(
             "dump",
             from_fn_async(dump)
                 .with_metadata("admin", Value::Bool(true))
                 .no_cli(),
         )
-        .subcommand("apply", from_fn_async(cli_apply).no_display())
+        .subcommand(
+            "apply",
+            from_fn_async(cli_apply)
+                .no_display()
+                .with_about("Update a db record"),
+        )
         .subcommand(
             "apply",
             from_fn_async(apply)

core/startos/src/registry/mod.rs

@@ -82,18 +82,32 @@ pub fn registry_api<C: Context>() -> ParentHandler<C> {
             "index",
             from_fn_async(get_full_index)
                 .with_display_serializable()
+                .with_about("List info including registry name and packages")
                 .with_call_remote::<CliContext>(),
         )
         .subcommand(
             "info",
             from_fn_async(get_info)
                 .with_display_serializable()
+                .with_about("Display registry name, icon, and package categories")
                 .with_call_remote::<CliContext>(),
         )
-        .subcommand("os", os::os_api::<C>())
-        .subcommand("package", package::package_api::<C>())
-        .subcommand("admin", admin::admin_api::<C>())
-        .subcommand("db", db::db_api::<C>())
+        .subcommand(
+            "os",
+            os::os_api::<C>().with_about("Commands related to OS assets and versions"),
+        )
+        .subcommand(
+            "package",
+            package::package_api::<C>().with_about("Commands to index, add, or get packages"),
+        )
+        .subcommand(
+            "admin",
+            admin::admin_api::<C>().with_about("Commands to add or list admins or signers"),
+        )
+        .subcommand(
+            "db",
+            db::db_api::<C>().with_about("Commands to interact with the db i.e. dump and apply"),
+        )
 }
 
 pub fn registry_router(ctx: RegistryContext) -> Router {

core/startos/src/registry/os/asset/get.rs

@@ -26,11 +26,21 @@ use crate::util::io::open_file;
 pub fn get_api<C: Context>() -> ParentHandler<C> {
     ParentHandler::new()
         .subcommand("iso", from_fn_async(get_iso).no_cli())
-        .subcommand("iso", from_fn_async(cli_get_os_asset).no_display())
+        .subcommand(
+            "iso",
+            from_fn_async(cli_get_os_asset)
+                .no_display()
+                .with_about("Download iso"),
+        )
         .subcommand("img", from_fn_async(get_img).no_cli())
-        .subcommand("img", from_fn_async(cli_get_os_asset).no_display())
+        .subcommand(
+            "img",
+            from_fn_async(cli_get_os_asset)
+                .no_display()
+                .with_about("Download img"),
+        )
         .subcommand("squashfs", from_fn_async(get_squashfs).no_cli())
-        .subcommand("squashfs", from_fn_async(cli_get_os_asset).no_display())
+        .subcommand("squashfs", from_fn_async(cli_get_os_asset).no_display().with_about("Download squashfs"))
 }
 
 #[derive(Debug, Deserialize, Serialize, TS)]

core/startos/src/registry/os/asset/mod.rs

@@ -7,8 +7,21 @@ pub mod sign;
 pub fn asset_api<C: Context>() -> ParentHandler<C> {
     ParentHandler::new()
         .subcommand("add", add::add_api::<C>())
-        .subcommand("add", from_fn_async(add::cli_add_asset).no_display())
+        .subcommand(
+            "add",
+            from_fn_async(add::cli_add_asset)
+                .no_display()
+                .with_about("Add asset to registry"),
+        )
         .subcommand("sign", sign::sign_api::<C>())
-        .subcommand("sign", from_fn_async(sign::cli_sign_asset).no_display())
-        .subcommand("get", get::get_api::<C>())
+        .subcommand(
+            "sign",
+            from_fn_async(sign::cli_sign_asset)
+                .no_display()
+                .with_about("Sign file and add to registry index"),
+        )
+        .subcommand(
+            "get",
+            get::get_api::<C>().with_about("Commands to download image, iso, or squashfs files"),
+        )
 }

core/startos/src/registry/os/mod.rs

@@ -15,8 +15,16 @@ pub fn os_api<C: Context>() -> ParentHandler<C> {
             "index",
             from_fn_async(index::get_os_index)
                 .with_display_serializable()
+                .with_about("List index of OS versions")
                 .with_call_remote::<CliContext>(),
         )
-        .subcommand("asset", asset::asset_api::<C>())
-        .subcommand("version", version::version_api::<C>())
+        .subcommand(
+            "asset",
+            asset::asset_api::<C>().with_about("Commands to add, sign, or get registry assets"),
+        )
+        .subcommand(
+            "version",
+            version::version_api::<C>()
+                .with_about("Commands to add, remove, or list versions or version signers"),
+        )
 }

core/startos/src/registry/os/version/mod.rs

@@ -26,6 +26,7 @@ pub fn version_api<C: Context>() -> ParentHandler<C> {
                 .with_metadata("admin", Value::Bool(true))
                 .with_metadata("get_signer", Value::Bool(true))
                 .no_display()
+                .with_about("Add OS version")
                 .with_call_remote::<CliContext>(),
         )
         .subcommand(
@@ -33,9 +34,13 @@ pub fn version_api<C: Context>() -> ParentHandler<C> {
             from_fn_async(remove_version)
                 .with_metadata("admin", Value::Bool(true))
                 .no_display()
+                .with_about("Remove OS version")
                 .with_call_remote::<CliContext>(),
         )
-        .subcommand("signer", signer::signer_api::<C>())
+        .subcommand(
+            "signer",
+            signer::signer_api::<C>().with_about("Add, remove, and list version signers"),
+        )
         .subcommand(
             "get",
             from_fn_async(get_version)
@@ -43,6 +48,7 @@ pub fn version_api<C: Context>() -> ParentHandler<C> {
                 .with_custom_display_fn(|handle, result| {
                     Ok(display_version_info(handle.params, result))
                 })
+                .with_about("Get OS versions and related version info")
                 .with_call_remote::<CliContext>(),
         )
 }

core/startos/src/registry/os/version/signer.rs

@@ -21,6 +21,7 @@ pub fn signer_api<C: Context>() -> ParentHandler<C> {
             from_fn_async(add_version_signer)
                 .with_metadata("admin", Value::Bool(true))
                 .no_display()
+                .with_about("Add version signer")
                 .with_call_remote::<CliContext>(),
         )
         .subcommand(
@@ -28,6 +29,7 @@ pub fn signer_api<C: Context>() -> ParentHandler<C> {
             from_fn_async(remove_version_signer)
                 .with_metadata("admin", Value::Bool(true))
                 .no_display()
+                .with_about("Remove version signer")
                 .with_call_remote::<CliContext>(),
         )
         .subcommand(
@@ -35,6 +37,7 @@ pub fn signer_api<C: Context>() -> ParentHandler<C> {
             from_fn_async(list_version_signers)
                 .with_display_serializable()
                 .with_custom_display_fn(|handle, result| Ok(display_signers(handle.params, result)))
+                .with_about("List version signers and related signer info")
                 .with_call_remote::<CliContext>(),
         )
 }

core/startos/src/registry/package/mod.rs

@@ -14,6 +14,7 @@ pub fn package_api<C: Context>() -> ParentHandler<C> {
             "index",
             from_fn_async(index::get_package_index)
                 .with_display_serializable()
+                .with_about("List packages and categories")
                 .with_call_remote::<CliContext>(),
         )
         .subcommand(
@@ -22,7 +23,12 @@ pub fn package_api<C: Context>() -> ParentHandler<C> {
                 .with_metadata("get_signer", Value::Bool(true))
                 .no_cli(),
         )
-        .subcommand("add", from_fn_async(add::cli_add_package).no_display())
+        .subcommand(
+            "add",
+            from_fn_async(add::cli_add_package)
+                .no_display()
+                .with_about("Add package to registry index"),
+        )
         .subcommand(
             "get",
             from_fn_async(get::get_package)
@@ -31,6 +37,7 @@ pub fn package_api<C: Context>() -> ParentHandler<C> {
                 .with_custom_display_fn(|handle, result| {
                     get::display_package_info(handle.params, result)
                 })
+                .with_about("List installation candidate package(s)")
                 .with_call_remote::<CliContext>(),
         )
 }