Merge branch 'maint'

* maint:
  Extend parse-options test suite
  api-parse-options.txt: Introduce documentation for parse options API
  parse-options.c: fix documentation syntax of optional arguments
  api-builtin.txt: update and fix typo

diff --combined parse-options.c
index 8071711e5db4ae1e2efad7b905c6a1ef0add1467,f8d52e21fe1f0bced3d4abf081f02000bbd7df62..b8bde2b04a14936787392babf5e0ec0a9e3ef1a7
--- 1/parse-options.c
--- 2/parse-options.c
+++ b/parse-options.c
@@@ -312,12 -312,8 +312,12 @@@ void usage_with_options_internal(const 
        fprintf(stderr, "usage: %s\n", *usagestr++);
        while (*usagestr && **usagestr)
                fprintf(stderr, "   or: %s\n", *usagestr++);
 -      while (*usagestr)
 -              fprintf(stderr, "    %s\n", *usagestr++);
 +      while (*usagestr) {
 +              fprintf(stderr, "%s%s\n",
 +                              **usagestr ? "    " : "",
 +                              *usagestr);
 +              usagestr++;
 +      }
  
        if (opts->type != OPTION_GROUP)
                fputc('\n', stderr);
@@@ -348,7 -344,10 +348,10 @@@
                        break;
                case OPTION_INTEGER:
                        if (opts->flags & PARSE_OPT_OPTARG)
-                               pos += fprintf(stderr, "[<n>]");
+                               if (opts->long_name)
+                                       pos += fprintf(stderr, "[=<n>]");
+                               else
+                                       pos += fprintf(stderr, "[<n>]");
                        else
                                pos += fprintf(stderr, " <n>");
                        break;
@@@ -359,12 -358,18 +362,18 @@@
                case OPTION_STRING:
                        if (opts->argh) {
                                if (opts->flags & PARSE_OPT_OPTARG)
-                                       pos += fprintf(stderr, " [<%s>]", opts->argh);
+                                       if (opts->long_name)
+                                               pos += fprintf(stderr, "[=<%s>]", opts->argh);
+                                       else
+                                               pos += fprintf(stderr, "[<%s>]", opts->argh);
                                else
                                        pos += fprintf(stderr, " <%s>", opts->argh);
                        } else {
                                if (opts->flags & PARSE_OPT_OPTARG)
-                                       pos += fprintf(stderr, " [...]");
+                                       if (opts->long_name)
+                                               pos += fprintf(stderr, "[=...]");
+                                       else
+                                               pos += fprintf(stderr, "[...]");
                                else
                                        pos += fprintf(stderr, " ...");
                        }

diff --combined t/t1502-rev-parse-parseopt.sh
index 7cdd70a188f7b177652ad8c8d680d36a0d5a9bf7,3508d0a612487be824dfe62eaf2377bc05ae8c17..997002d4c40dd8e66e3be5a701e3d99bab1c57c4
--- 1/t/t1502-rev-parse-parseopt.sh
--- 2/t/t1502-rev-parse-parseopt.sh
+++ b/t/t1502-rev-parse-parseopt.sh
@@@ -5,7 -5,7 +5,7 @@@ test_description='test git rev-parse --
  
  cat > expect.err <<EOF
  usage: some-command [options] <args>...
 -    
 +
      some-command does foo and bar!
  
      -h, --help            show the help
@@@ -13,7 -13,7 +13,7 @@@
      --bar ...             some cool option --bar with an argument
  
  An option group Header
-     -C [...]              option C with an optional argument
+     -C[...]               option C with an optional argument
  
  Extras
      --extra1              line above used to cause a segfault but no longer does