Fixed YAML output for a list of maps

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 cccb8eb084cec52be21ec3ee46de633dbd7f6e61..8ad16047e5afb58b250a6346bb1e833f22a3b19d 100644
--- a/pkg/docgen/lib/dart2yaml.dart
+++ b/pkg/docgen/lib/dart2yaml.dart
@@ -20,28 +20,29 @@ String getYamlString(Map documentData) {
  * This recursive function adds to its input StringBuffer and builds
  * a YAML string from the input Map.
  */

[Alan Knight, 2013/07/25 17:46:42]

This could use some documentation for the parameters. With "isList" it isn't
obvious what's a list.

[Tate Mandel, 2013/07/25 22:01:53]

Done.

-// TODO(tmandel): Fix quotes with String objects.
-void _addLevel(StringBuffer yaml, Map documentData, int level) {
-  documentData.keys.forEach( (key) {
+void _addLevel(StringBuffer yaml, Map documentData, int level,
+               {bool isList: false}) {
+  documentData.keys.forEach((key) {
     _calcSpaces(level, yaml);
+    if (isList && key == documentData.keys.first) {

[Alan Knight, 2013/07/25 17:46:42]

Since the order of keys is non-deterministic, I assume this means documentData
should always have one element?

In general, we seem to have some strong assumptions about the structure of
documentData, and those should probably be documented.

[Tate Mandel, 2013/07/25 22:01:53]

documentData can have many elements, but the first one should be marked with a
'-' to denote that it's the start of a new record in the collection. See example
2.4 at http://www.yaml.org/spec/1.2/spec.html#id2759963. 

If we are outputting YAML for a list of maps, we have to mark the first key of
each map with a '-' to denote that it's the start of a separate member of that
list.

If it is non-deterministic, then maybe we should alphabetize keys first to
ensure the same key is at the beginning for each member of the outer list?

[Alan Knight, 2013/07/25 23:25:04]

I think the ordering is actually quite messy. If I understand, the ordering for
a literal map is deterministic, because it is in Javascript and that was likely
to break people's assumptions. And there's obvious a class that preserves that
ordering, even though what's underneath is a hash table, and doesn't. So if
we're relying on the "first" key in a map, we should make sure we're always
going to be using the kind of map that preserves that order, or else doing
something like sorting ourselves to ensure it.

[Tate Mandel, 2013/07/26 20:33:04]

Done.

+      yaml.write("- ");
+      level++;
+    }
     yaml.write("\"$key\" : ");
-
     if (documentData[key] is Map) {
       yaml.write("\n");
       _addLevel(yaml, documentData[key], level + 1);
-
     } else if (documentData[key] is List) {
       var elements = documentData[key];
       yaml.write("\n");
       elements.forEach( (element) {
         if (element is Map) {
-          _addLevel(yaml, element, level + 1);
+          _addLevel(yaml, element, level + 1, isList: true);
         } else {
           _calcSpaces(level + 1, yaml);
           yaml.write("- ${_processElement(element)}");
         }
       });
-      
     } else {
       yaml.write(_processElement(documentData[key]));
     }