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, 20 insertions, 2 deletions

diff --git a/sinksh/syntax_modules/sink_inspect.cpp b/sinksh/syntax_modules/sink_inspect.cpp
index f9cc50a..355efa3 100644
--- a/sinksh/syntax_modules/sink_inspect.cpp
+++ b/sinksh/syntax_modules/sink_inspect.cpp
@@ -55,10 +55,14 @@ QString parse(const QByteArray &bytes)
     }
 }
 
+Syntax::List syntax();
+
 bool inspect(const QStringList &args, State &state)
 {
     if (args.isEmpty()) {
-        state.printError(QObject::tr("Options: [--resource $resource] ([--db $db] [--filter $id] [--showinternal] | [--validaterids $type] | [--fulltext [$id]])"));
+        //state.printError(QObject::tr("Options: [--resource $resource] ([--db $db] [--filter $id] [--showinternal] | [--validaterids $type] | [--fulltext [$id]])"));
+        state.printError(syntax()[0].usage());
+        return false;
     }
     auto options = SyntaxTree::parseOptions(args);
     auto resource = SinkshUtils::parseUid(options.options.value("resource").value(0).toUtf8());
@@ -236,7 +240,21 @@ bool inspect(const QStringList &args, State &state)
 
 Syntax::List syntax()
 {
-    Syntax state("inspect", QObject::tr("Inspect database for the resource requested"), &SinkInspect::inspect, Syntax::NotInteractive);
+    Syntax state("inspect", QObject::tr("Inspect database for the resource requested"),
+        &SinkInspect::inspect, Syntax::NotInteractive);
+
+    state.addParameter("resource",
+        { .name = "resource", .help = "Which resource to inspect", .required = true });
+    state.addParameter("db",
+        { .name = "database", .help = "Which database to inspect"});
+    state.addParameter("filter",
+        { .name = "id", .help = "A specific id to filter the results by (currently not working)"});
+    state.addFlag("showinternal", "Show internal fields only");
+    state.addParameter("validaterids",
+        { .name = "type", .help = "Validate remote Ids of the given type"});
+    state.addParameter("fulltext",
+        { .name = "id", .help = "If 'id' is not given, count the number of fulltext documents. Else, print the terms of the document with the given id"});
+
     state.completer = &SinkshUtils::resourceCompleter;
 
     return Syntax::List() << state;