Remove sorting of allowedHelp maps

pkgs/args/CHANGELOG.md

@@ -1,5 +1,7 @@
 ## 2.6.1-wip
 
+* Remove sorting of the `allowedHelp` argument in usage output. Ordering will
+  depend on key order for the passed `Map`.
 * Fix the repository URL in `pubspec.yaml`.
 * Added option `hideNegatedUsage` to `ArgParser.flag()` allowing a flag to be
   `negatable` without showing it in the usage text.

pkgs/args/lib/src/arg_parser.dart

@@ -177,6 +177,12 @@ class ArgParser {
   ///
   /// The [allowedHelp] argument is a map from values in [allowed] to
   /// documentation for those values that will be included in [usage].
+  /// The map may include a subset of the allowed values.
+  /// Additional values that are not in [allowed] should be omitted, however
+  /// there is no validation.
+  /// When both [allowed] and [allowedHelp] are passed, only [allowed] will
+  /// be validated at parse time, and only [allowedHelp] will be included in
+  /// usage output.
   ///
   /// The [defaultsTo] argument indicates the value this option will have if the
   /// user doesn't explicitly pass it in (or `null` by default).
@@ -231,6 +237,12 @@ class ArgParser {
   ///
   /// The [allowedHelp] argument is a map from values in [allowed] to
   /// documentation for those values that will be included in [usage].
+  /// The map may include a subset of the allowed values.
+  /// Additional values that are not in [allowed] should be omitted, however
+  /// there is no validation.
+  /// When both [allowed] and [allowedHelp] are passed, only [allowed] will
+  /// be validated at parse time, and only [allowedHelp] will be included in
+  /// usage output.
   ///
   /// The [defaultsTo] argument indicates the values this option will have if
   /// the user doesn't explicitly pass it in (or `[]` by default).

pkgs/args/lib/src/usage.dart

@@ -90,10 +90,8 @@ class _Usage {
     if (option.help != null) _write(2, option.help!);
 
     if (option.allowedHelp != null) {
-      var allowedNames = option.allowedHelp!.keys.toList();
-      allowedNames.sort();
       _newline();
-      for (var name in allowedNames) {
+      for (var name in option.allowedHelp!.keys) {
         _write(1, _allowedTitle(option, name));
         _write(2, option.allowedHelp![name]!);
       }

pkgs/args/test/usage_test.dart

@@ -216,10 +216,10 @@ void main() {
       validateUsage(parser, '''
           --suit              Like in cards
 
+                [spades]      Swords of a soldier
                 [clubs]       Weapons of war
                 [diamonds]    Money for this art
                 [hearts]      The shape of my heart
-                [spades]      Swords of a soldier
           ''');
     });
 
@@ -244,10 +244,10 @@ void main() {
       validateUsage(parser, '''
           --suit                     Like in cards
 
+                [spades]             Swords of a soldier
                 [clubs] (default)    Weapons of war
                 [diamonds]           Money for this art
                 [hearts]             The shape of my heart
-                [spades]             Swords of a soldier
           ''');
     });
 
@@ -271,10 +271,10 @@ void main() {
       validateUsage(parser, '''
           --suit                      Like in cards
 
+                [spades]              Swords of a soldier
                 [clubs] (default)     Weapons of war
                 [diamonds]            Money for this art
                 [hearts] (default)    The shape of my heart
-                [spades]              Swords of a soldier
           ''');
     });