Improve documentation of SinkSH

Summary:
- Add support for positional arguments, options, flags in the syntax tree
- Add automatic generation of usage string

TODO:

- ~~Better document the `--reduce` option in the `list` command~~
- Get the parent command for sub-commands so we could show help for `trace on` and not just `on`
- Pass the syntax to the implementation of the command so commands can easily show help on wrong usage. Also, SyntaxTree could do automatic input validation in the future, this could also help.
- Even with the new documentation, some command could still be confusing. Should we add some usage examples?

Reviewers: cmollekopf

Reviewed By: cmollekopf

Tags: #sink

Differential Revision: https://phabricator.kde.org/D14547

1 files changed, 16 insertions, 2 deletions

diff --git a/sinksh/syntax_modules/sink_list.cpp b/sinksh/syntax_modules/sink_list.cpp
index 32fae4f..eef188b 100644
--- a/sinksh/syntax_modules/sink_list.cpp
+++ b/sinksh/syntax_modules/sink_list.cpp
@@ -39,6 +39,8 @@
 namespace SinkList
 {
 
+Syntax::List syntax();
+
 static QByteArray compressId(bool compress, const QByteArray &id)
 {
     if (!compress) {
@@ -117,7 +119,7 @@ QStringList printToList(const Sink::ApplicationDomain::ApplicationDomainType &o,
 bool list(const QStringList &args_, State &state)
 {
     if (args_.isEmpty()) {
-        state.printError(QObject::tr("Options: $type [--resource $resource] [--compact] [--filter $property=$value] [--id $id] [--showall|--show $property] [--reduce $reduceProperty:$selectorProperty] [--sort $sortProperty] [--limit $count]"));
+        state.printError(syntax()[0].usage());
         return false;
     }
 
@@ -127,7 +129,7 @@ bool list(const QStringList &args_, State &state)
     Sink::Query query;
     query.setId("list");
     if (!SinkshUtils::applyFilter(query, options)) {
-        state.printError(QObject::tr("Options: $type [--resource $resource] [--compact] [--filter $property=$value] [--showall|--show $property]"));
+        state.printError(syntax()[0].usage());
         return false;
     }
 
@@ -198,6 +200,18 @@ bool list(const QStringList &args_, State &state)
 Syntax::List syntax()
 {
     Syntax list("list", QObject::tr("List all resources, or the contents of one or more resources."), &SinkList::list, Syntax::NotInteractive);
+
+    list.addPositionalArgument({.name = "type", .help = "The type of content to list (resource, identity, account, mail, etc.)"});
+    list.addParameter("resource", { .name = "resource", .help = "List only the content of the given resource" });
+    list.addFlag("compact", "Use a compact view (reduces the size of IDs)");
+    list.addParameter("filter", { .name = "property=$value", .help = "Filter the results" });
+    list.addParameter("id", { .name = "id", .help = "List only the content with the given ID" });
+    list.addFlag("showall", "Show all properties");
+    list.addParameter("show", { .name = "property", .help = "Only show the given property" });
+    list.addParameter("reduce", { .name = "property:$selectorProperty", .help = "Combine the result with the same $property, sorted by $selectorProperty" });
+    list.addParameter("sort", { .name = "property", .help = "Sort the results according to the given property" });
+    list.addParameter("limit", { .name = "count", .help = "Limit the results" });
+
     list.completer = &SinkshUtils::resourceOrTypeCompleter;
     return Syntax::List() << list;
 }