Fixed parameters losing their original order

pkg/docgen/lib/dart2yaml.dart

Index: pkg/docgen/lib/dart2yaml.dart
diff --git a/pkg/docgen/lib/dart2yaml.dart b/pkg/docgen/lib/dart2yaml.dart
index 57ca7fe3938605f55a8dfac4efe5199699e4e91f..cbd28ac7d2079535d8862ae1acc49441cd62602f 100644
--- a/pkg/docgen/lib/dart2yaml.dart
+++ b/pkg/docgen/lib/dart2yaml.dart
@@ -26,10 +26,11 @@ String getYamlString(Map documentData) {
  */
 void _addLevel(StringBuffer yaml, Map documentData, int level,
                {bool isList: false}) {
-  // Since the ordering of the keys could be non-deterministic, the keys
-  // are sorted to ensure consistency in the output.
+  // TODO(tmandel): The order of the keys could be nondeterministic, but it
+  // is insufficient to just sort the keys, as their order could be significant
+  // (i.e. parameters to a method). This should have a check that the map's key
+  // order is deterministic or something similar.

[Jennifer Messerly, 2013/08/16 21:43:32]

maybe check that documentData is LinkedHashMap or SplayTreeMap? Those two are
ordered consistently.

[Tate Mandel, 2013/08/16 21:53:41]

Are these the only two that are ordered consistently?

[Jennifer Messerly, 2013/08/16 22:05:49]

hmm, it's tricky. I guess it depends on who calls this function and what data
they supply, and if the order contract should be enforced here or at a higher
level in the code :)

Map by itself doesn't say anything about order. LinkedHashMap and SplayTreeMap
both guarantee an order, and plain HashMap does not, but with a custom type that
implements Map there's really no way to tell for sure.

[Tate Mandel, 2013/08/16 22:09:45]

I'd say it should be enforced elsewhere. We probably want to allow for the user
to decide how ordering should work. I updated the comment and reverted to the
initial version.

   var keys = documentData.keys.toList();
-  keys.sort();
   keys.forEach((key) {
     _calcSpaces(level, yaml);
     // Only the first entry of the map should be preceeded with a '-' since