Add better option descriptions (#72)

* Add better option descriptions

* Small fix in RdfInspect

* Small fix in RdfInspect

* Update src/main/scala/eu/neverblink/jelly/cli/command/Version.scala

Co-authored-by: Piotr Sowiński <ostrzycielnozyczek@gmail.com>

---------

Co-authored-by: Karolina Bogacka <karolina@neverblink.eu>
Co-authored-by: Piotr Sowiński <ostrzycielnozyczek@gmail.com>

Author: Karolina-Bogacka

src/main/scala/eu/neverblink/jelly/cli/JellyCommand.scala

@@ -7,8 +7,8 @@ import java.io.*
 import scala.compiletime.uninitialized
 
 case class JellyCommandOptions(
-    @HelpMessage("Add to run command in debug mode") debug: Boolean = false,
-    @HelpMessage("Add to silence any warnings") quiet: Boolean = false,
+    @HelpMessage("Add to run command in debug mode. ") debug: Boolean = false,
+    @HelpMessage("Add to silence any warnings. ") quiet: Boolean = false,
 )
 
 trait HasJellyCommandOptions:

src/main/scala/eu/neverblink/jelly/cli/command/Version.scala

@@ -3,6 +3,9 @@ package eu.neverblink.jelly.cli.command
 import caseapp.*
 import eu.neverblink.jelly.cli.*
 
+@HelpMessage(
+  "Prints the version of the jelly-cli utility and the Jelly-JVM library.",
+)
 case class VersionOptions(
     @Recurse
     common: JellyCommandOptions = JellyCommandOptions(),

src/main/scala/eu/neverblink/jelly/cli/command/rdf/RdfFromJelly.scala

@@ -15,13 +15,25 @@ import java.io.{InputStream, OutputStream}
 object RdfFromJellyPrint extends RdfCommandPrintUtil[RdfFormat.Writeable]:
   override val defaultFormat: RdfFormat = RdfFormat.NQuads
 
+@HelpMessage(
+  "Translates a Jelly-RDF stream to a different RDF format. \n" +
+    "If no input file is specified, the input is read from stdin.\n" +
+    "If no output file is specified, the output is written to stdout.\n" +
+    "If an error is detected, the program will exit with a non-zero code.\n" +
+    "Otherwise, the program will exit with code 0.\n" +
+    "Note: this command works in a streaming manner and scales well to large files",
+)
+@ArgsName("<file-to-convert>")
 case class RdfFromJellyOptions(
     @Recurse
     common: JellyCommandOptions = JellyCommandOptions(),
+    @HelpMessage(
+      "Output file to write the RDF to. If not specified, the output is written to stdout.",
+    )
     @ExtraName("to") outputFile: Option[String] = None,
-    @ValueDescription("Output format.")
     @HelpMessage(
-      RdfFromJellyPrint.helpMsg,
+      "RDF format Jelly should be translated to. " +
+        "If not explicitly specified, but output file supplied, the format is inferred from the file name. " + RdfFromJellyPrint.helpMsg,
     )
     @ExtraName("out-format") outputFormat: Option[String] = None,
 ) extends HasJellyCommandOptions

src/main/scala/eu/neverblink/jelly/cli/command/rdf/RdfInspect.scala

@@ -1,17 +1,36 @@
 package eu.neverblink.jelly.cli.command.rdf
 
-import caseapp.{ExtraName, Recurse}
+import caseapp.{ArgsName, ExtraName, HelpMessage, Recurse}
 import caseapp.core.RemainingArgs
 import eu.neverblink.jelly.cli.*
 import eu.neverblink.jelly.cli.command.rdf.util.{FrameInfo, JellyUtil, MetricsPrinter}
 import eu.ostrzyciel.jelly.core.proto.v1.*
 
 import java.io.InputStream
-
+@HelpMessage(
+  "Prints statistics about a Jelly-RDF stream.\n" +
+    "Statistics include: Jelly stream options and counts of various row types, " +
+    "including triples, quads, names, prefixes, " +
+    "namespaces, datatypes, and graphs.\n" +
+    "Output statistics are returned as a valid YAML. \n" +
+    "If no input file is specified, the input is read from stdin.\n" +
+    "If no output file is specified, the output is written to stdout.\n" +
+    "If an error is detected, the program will exit with a non-zero code.\n" +
+    "Otherwise, the program will exit with code 0.\n",
+  "Note: this command works in a streaming manner and scales well to large files",
+)
+@ArgsName("<file-to-inspect>")
 case class RdfInspectOptions(
     @Recurse
     common: JellyCommandOptions = JellyCommandOptions(),
+    @HelpMessage(
+      "File to write the output statistics to. If not specified, the output is written to stdout.",
+    )
     @ExtraName("to") outputFile: Option[String] = None,
+    @HelpMessage(
+      "Whether to print the statistics per frame (default: false). " +
+        "If true, the statistics are computed and printed separately for each frame in the stream.",
+    )
     @ExtraName("per-frame") perFrame: Boolean = false,
 ) extends HasJellyCommandOptions
 

src/main/scala/eu/neverblink/jelly/cli/command/rdf/RdfToJelly.scala

@@ -15,13 +15,26 @@ import scala.util.Using
 object RdfToJellyPrint extends RdfCommandPrintUtil[RdfFormat.Readable]:
   override val defaultFormat: RdfFormat = RdfFormat.NQuads
 
+@HelpMessage(
+  "Translates an RDF file to a Jelly-RDF stream. \n" +
+    "If no input file is specified, the input is read from stdin.\n" +
+    "If no output file is specified, the output is written to stdout.\n" +
+    "If an error is detected, the program will exit with a non-zero code.\n" +
+    "Otherwise, the program will exit with code 0.\n" +
+    "Note: this command works in a streaming manner and scales well to large files. ",
+)
+@ArgsName("<file-to-convert>")
 case class RdfToJellyOptions(
     @Recurse
     common: JellyCommandOptions = JellyCommandOptions(),
+    @HelpMessage(
+      "Output file to write the Jelly to. If not specified, the output is written to stdout.",
+    )
     @ExtraName("to") outputFile: Option[String] = None,
-    @ValueDescription("Input format.")
     @HelpMessage(
-      RdfToJellyPrint.helpMsg,
+      "RDF format of the data that should be translated to Jelly. " +
+        "If not explicitly specified, but input file supplied, the format is inferred from the file name. " +
+        RdfToJellyPrint.helpMsg,
     )
     @ExtraName("in-format") inputFormat: Option[String] = None,
     @Recurse