gsu: Improve documentation of _gsu_get_command_regex().

Although this function is private, it is central to the subcommand
part of gsu and should thus be properly documented. The new text is
more precise about the meaning of the regular expression that is used
to identify subcommands.

diff --git a/misc/gsu/subcommand b/misc/gsu/subcommand
index f1685aa1e416af8bf3ddb3d78a2a93ec1f9bacaa..a04b8dece11660f1b95946c8108f5f9ceacf8a76 100644 (file)
--- a/misc/gsu/subcommand
+++ b/misc/gsu/subcommand
@@ -11,8 +11,16 @@ _gsu_usage()
        gsu_short_msg "# Usage: $_gsu_self command [options]"
 }
 
-# Each line matching this is recognized as a subcommand. The name of the may be
-# given as $1. In any case the subcommand is the first subexpression.
+# Return an extended regular expression to match against $0.
+#
+# When called without argument, the expression matches all lines which define a
+# subcommand.
+#
+# If an argument is given, the returned expression matches only the subcommand
+# passed as $1. This is useful to tell if a string is a valid subcommand.
+#
+# Regardless of whether an argument is given, the returned expression contains
+# exactly one parenthesized subexpression for matching the command name.
 _gsu_get_command_regex()
 {
        local cmd="${1:-[-a-zA-Z_0-9]+}"