Fix out-of-date documentation

Author: hlship

doc/dispatch.md

@@ -35,19 +35,11 @@ the tool-level `help` command.
 
 You may also specify groups; groups are containers of sub-commands, and may themselves contain sub-groups.
 
-Groups serve two purposes:
-
-* They divide the list of commands into sequences of related commands
-
-* They may optionally define a command group name, which isolates the commands within the group; for example, the way the `docker` command has sub-commands such as `compose` and `volume`, each containing further sub-commands.
-
-The group map is keyed on a command name, and its value defines the group; like the top-level map,
+The group map is keyed on a group name, and its value defines the group; like the top-level map,
 a group will contain keys for :namespaces, :title, :doc, and :groups (for more deeply nested groups).
 
 The group's :title is used in the tool help summary.
-
-Many of these options are optional; details in the [dispatch](dispatch.md) docs.
-               
+ 
 ![Top Level Help](images/top-level-help.png)                              
 
 In the above example, `colors`, `completions`, `help`, `job-status-demo`, and `kill-port` are commands.
@@ -60,7 +52,8 @@ The :doc and :title group options may be omitted.
 If :doc is omitted, then `dispatch` will search the group's namespaces, and use the first namespace docstring
 it finds.
 
-If :title is omitted, then the first line of the docstring, up to the first `.`, will be used as the title.
+If :title is omitted, then the first sentence of the :doc key, up to (but not including) 
+the first `.`, will be used as the title.
 
 ## Callbacks
 
@@ -76,4 +69,4 @@ to invoke.
 
 The :pre-invoke callback is invoked once a specific command function is identified.
 The callback is invoked immediately before the command function is invoked; it is passed the 
-command map, and a seq of remaining arguments (that will be passed to the command function).
+command map, and a seq of remaining arguments (that will then be passed to the command function).