Consistently use . to finish sentences. (#8)

Give more guidance on how to write text.

Author: floitsch

examples/main.toit

@@ -13,24 +13,25 @@ The command will have the following help:
 ```
 This is an imaginary fleet manager for a fleet of Toit devices.
 
-It can not be used to manage the fleet, for example by adding or removing devices.
+It can not be used to manage the fleet, for example
+  by adding or removing devices.
 
 Usage:
   examples/main.toit <command>
 
 Commands:
   device  Manage a particular device.
-  help    Show help for a command
-  status  Shows the status of the fleet
+  help    Show help for a command.
+  status  Shows the status of the fleet.
 
 Options:
-  -h, --help  Show help for this command
+  -h, --help  Show help for this command.
 
 Examples:
-  # Do a soft-reset of device 'foo'.
+  # Do a soft-reset of device 'foo':
   fleet_manager device --device=foo reset -m soft
 
-  # Show a detailed status of the fleet
+  # Show a detailed status of the fleet:
   fleet_manager status --verbose
 ```
 
@@ -44,18 +45,18 @@ Usage:
   examples/main.toit device reset --mode=<hard|soft> [<options>]
 
 Options:
-  -f, --force           Force the reset even if the device is active
-  -h, --help            Show help for this command
-  -m, --mode hard|soft  The reset mode to use (required)
+  -f, --force           Force the reset even if the device is active.
+  -h, --help            Show help for this command.
+  -m, --mode hard|soft  The reset mode to use. (required)
 
 Global options:
-  -d, --device string  The device to operate on
+  -d, --device string  The device to operate on.
 
 Examples:
-  # Do a soft-reset of device 'foo'.
+  # Do a soft-reset of device 'foo':
   fleet_manager device --device=foo reset -m soft
 
-  # Do a hard-reset
+  # Do a hard-reset:
   fleet_manager device reset --mode=hard
 ```
 */
@@ -67,7 +68,8 @@ main arguments:
       --long_help="""
         This is an imaginary fleet manager for a fleet of Toit devices.
 
-        It can not be used to manage the fleet, for example by adding or removing devices.
+        It can not be used to manage the fleet, for example
+          by adding or removing devices.
         """
 
   root_cmd.add create_status_command
@@ -79,14 +81,14 @@ main arguments:
 
 create_status_command -> cli.Command:
   return cli.Command "status"
-      --short_help="Shows the status of the fleet"
+      --short_help="Shows the status of the fleet:"
       --options=[
         cli.Flag "verbose" --short_name="v" --short_help="Show more details." --multi,
         cli.OptionInt "max-lines" --short_help="Maximum number of lines to show." --default=10,
       ]
       --examples=[
-        cli.Example "Show the status of the fleet" --arguments="",
-        cli.Example "Show a detailed status of the fleet" --arguments="--verbose"
+        cli.Example "Show the status of the fleet:" --arguments="",
+        cli.Example "Show a detailed status of the fleet:" --arguments="--verbose"
             --global_priority=7,  // Show this example for the root command.
       ]
       --run=:: fleet_status it
@@ -118,7 +120,7 @@ create_device_command -> cli.Command:
         """
       --options=[
         cli.OptionString "device" --short_name="d"
-            --short_help="The device to operate on"
+            --short_help="The device to operate on."
       ]
   device_cmd.add create_reset_command
   return device_cmd
@@ -132,19 +134,19 @@ create_reset_command -> cli.Command:
         """
       --options=[
         cli.OptionEnum "mode" ["hard", "soft"]
-            --short_help="The reset mode to use"
+            --short_help="The reset mode to use."
             --short_name="m"
             --required,
         cli.Flag "force" --short_name="f"
-            --short_help="Force the reset even if the device is active",
+            --short_help="Force the reset even if the device is active.",
       ]
       --examples=[
         cli.Example
-            "Do a soft-reset of device 'foo'."
+            "Do a soft-reset of device 'foo':"
             --arguments="--device=foo -m soft"
             --global_priority=5,  // Include this example for super commands.
         cli.Example
-            "Do a hard-reset"
+            "Do a hard-reset:"
             --arguments="--mode=hard",
       ]
       --run=:: reset_device it

src/cli.toit

@@ -75,9 +75,12 @@ class Command:
   The $usage is usually constructed from the name and the arguments of the command, but can
     be provided explicitly if a different usage string is desired.
 
-  The $short_help is a short (one line) description of the command.
+  The $long_help is a longer description of the command that can span multiple lines. Use
+    indented lines to continue paragraphs (just like toitdoc).
 
-  The $long_help is a longer description of the command that can span multiple lines.
+  The $short_help is a short description of the command. In most cases this help is a single
+    line, but it can span multiple lines/paragraphs if necessary. Use indented lines to
+    continue paragraphs (just like toitdoc).
   */
   constructor .name --.usage=null --.short_help=null --.long_help=null --.examples=[] \
       --.aliases=[] --.options=[] --.rest=[] --.subcommands=[] --hidden/bool=false \
@@ -222,6 +225,29 @@ abstract class Option:
   is_multi/bool
   should_split_commas/bool
 
+  /**
+  Creates an option with the given $name.
+
+  The $name sets the name of the option. It must be unique among all options of a command.
+    It is also used to extract the parsed value from the $Parsed object.
+
+  The $short_name is optional and must be a single-character string when provided.
+
+  The $short_help is optional and is used for help output. It should be a full sentence, starting
+    with a capital letter and ending with a period.
+
+  If $required is true, then the option must be provided. Otherwise, it is optional.
+
+  If $hidden is true, then the option is not shown in help output. Rest arguments must not be
+    hidden.
+
+  If $multi is true, then the option can be provided multiple times. The parsed value will
+    be a list of strings.
+
+  If $split_commas is true, then $multi must be true too. Values given to this option are then
+    split on commas. For example, `--option a,b,c` will result in the list `["a", "b", "c"]`.
+
+  */
   constructor .name --.short_name --.short_help --required --hidden --multi --split_commas:
     is_required = required
     is_hidden = hidden
@@ -277,27 +303,12 @@ class OptionString extends Option:
   /**
   Creates a new string option.
 
-  The $name sets the name of the option. It must be unique among all options of a command.
-    It is also used to extract the parsed value from the $Parsed object.
-
   The $default value is null.
+
   The $type is set to 'string', but can be changed to something else. The $type is
     only used for help output.
 
-  The $short_name is optional and must be a single-character string when provided.
-
-  The $short_help is optional and is used for help output.
-
-  If $required is true, then the option must be provided. Otherwise, it is optional.
-
-  If $hidden is true, then the option is not shown in help output. Rest arguments must not be
-    hidden.
-
-  If $multi is true, then the option can be provided multiple times. The parsed value will
-    be a list of strings.
-
-  If $split_commas is true, then $multi must be true too. Values given to this option are then
-    split on commas. For example, `--option a,b,c` will result in the list `["a", "b", "c"]`.
+  See $Option.constructor for the other parameters.
   */
   constructor name/string
       --.default=null
@@ -337,7 +348,10 @@ class OptionEnum extends Option:
 
   The $values list provides the list of valid values for this option.
 
-  See $OptionString.constructor for the other parameters.
+  The $default value is null.
+  The $type defaults to a string joining all $values with a '|'.
+
+  See $Option.constructor for the other parameters.
   */
   constructor name/string .values/List
       --.default=null
@@ -367,7 +381,6 @@ class OptionEnum extends Option:
 An option that must be an integer value.
 
 The $parse function ensures that the value is an integer.
-The $type defaults to "int".
 */
 class OptionInt extends Option:
   default/int?
@@ -376,7 +389,10 @@ class OptionInt extends Option:
   /**
   Creates a new integer option.
 
-  See $OptionString.constructor for a description of the parameters.
+  The $default value is null.
+  The $type defaults to "int".
+
+  See $Option.constructor for the other parameters.
   */
   constructor name/string
       --.default=null
@@ -414,7 +430,10 @@ class Flag extends Option:
   /**
   Creates a new flag.
 
-  See $OptionString.constructor for a description of the parameters.
+  The $default value is null.
+  The $type is only visible when using this option as a rest argument and is then "true|false"
+
+  See $Option.constructor for the other parameters.
   */
   constructor name/string
       --.default=null
@@ -452,7 +471,9 @@ class Example:
   Creates an example.
 
   The $description should describe the example without any context. This is especially true
-    if the $global_priority is greater than 0 (see below).
+    if the $global_priority is greater than 0 (see below). It should start with a capital
+    letter and finish with a ":". It may contain newlines. Use indentation to group
+    paragraphs (just like toitdoc).
 
   The $arguments is a string containing the arguments to this command (or to super commands).
     The help generator parses the arguments and assigns all options to the corresponding commands.

src/help_generator_.toit

@@ -199,7 +199,7 @@ class HelpGenerator:
       commands_and_help.add [subcommand.name, help_str]
 
     if not has_help_subcommand and is_root_command_:
-      commands_and_help.add ["help", "Show help for a command"]
+      commands_and_help.add ["help", "Show help for a command."]
 
     sorted_commands := commands_and_help.sort: | a/List b/List | a[0].compare_to b[0]
     write_table_ sorted_commands --indentation=2
@@ -236,7 +236,7 @@ class HelpGenerator:
       if not has_help_flag:
         options = options.copy
         short_name := has_short_help_flag ? null : "h"
-        help_flag := Flag "help" --short_name=short_name --short_help="Show help for this command"
+        help_flag := Flag "help" --short_name=short_name --short_help="Show help for this command."
         options.add help_flag
 
     sorted_options := options.sort: | a/Option b/Option | a.name.compare_to b.name