Both halves of the HTMLDoc to JSON doc converter!

tools/html-json-doc/lib/JsonToHtml.dart

+// Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/**
+ * Library for taking a JSON file and putting the comments located within into
+ * the HTML files the comments are associated with.
+ *
+ * The format of the JSON file is:
+ *     {

[Bob Nystrom, 2012/11/26 22:00:19]

Put a blank line above this one. Dartdoc/markdown require a blank line to
separate code blocks from other content.

[Andrei Mouravski, 2012/11/27 03:11:45]

Done.

+ *       "$filename":
+ *         {
+ *           "$lineInHtml":
+ *             [
+ *               "lines of comment",
+ *               "here"
+ *             ]
+ *          },
+ *       ...
+ *     }
+ */
+library jsonToHtml;
+
+import 'dart:json';
+import 'dart:io';
+
+
+/// True if any errors were triggered through the conversion.
+bool _anyErrors = false;
+
+
+/**
+ * Take comments from [jsonPath] and apply them to all the files found in
+ * [htmlPath]. This will overwrite the files in htmlPath.
+ */
+Future<bool> convert(Path htmlPath, Path jsonPath) {
+  final completer = new Completer();
+
+  final jsonFile = new File.fromPath(jsonPath);
+
+  if (!jsonFile.existsSync()) {
+    print("ERROR: No JSON file found at: ${jsonPath}");
+    _anyErrors = true;
+    completer.complete(false);
+  }
+
+  var fileJson = {};
+  var jsonRead = Strings.join(jsonFile.readAsLinesSync(), '\n');

[Bob Nystrom, 2012/11/26 22:00:19]

jsonFile.readAsStringSync();

[Andrei Mouravski, 2012/11/27 03:11:45]

Done.

+
+  if (jsonRead == '') {
+    print('WARNING: no data read from ${jsonPath.filename}');
+    _anyErrors = true;
+    completer.complete(false);
+  } else {
+    fileJson = JSON.parse(jsonRead) as Map<String, Map<String, List<String>>>;

[Bob Nystrom, 2012/11/26 22:00:19]

What's the "as" for here?

[Andrei Mouravski, 2012/11/27 03:11:45]

At one point something was complaining.

+  }
+
+  // Find html files. (lister)

[Bob Nystrom, 2012/11/26 22:00:19]

There's a lot of overlap with the corresponding code in HtmlToJson. How about
refactoring the lister stuff out into a shared function?

[Andrei Mouravski, 2012/11/27 03:11:45]

TODO.

+  final htmlDir = new Directory.fromPath(htmlPath);
+  final lister = htmlDir.list(recursive: false);
+
+  lister.onFile = (String path) {
+    final name = new Path.fromNative(path).filename;
+
+    // Ignore private classes.
+    if (name.startsWith('_')) return;
+
+    // Ignore non-dart files.
+    if (!name.endsWith('.dart')) return;
+
+    File file = new File(path);
+
+    // TODO(amouravski): Handle missing file.
+    if (!file.existsSync()) {
+      print('ERROR: cannot find file: $path');
+      _anyErrors = true;
+      return;
+    }
+
+    if (!fileJson.containsKey(name)) {
+      print('WARNING: file found that is not in JSON: $path');
+      _anyErrors = true;
+      return;
+    }
+
+    var comments = fileJson[name];
+
+    _convertFile(file, comments);
+
+    fileJson.remove(name);
+  };
+
+  lister.onDone = (_) {
+
+    fileJson.forEach((key, _) {
+      print('WARNING: the following filename was found in the JSON but not in '
+          '${htmlDir.path}:\n"$key"');
+      _anyErrors = true;
+    });
+
+    completer.complete(_anyErrors);
+  };
+
+  return completer.future;
+}
+
+
+/**
+ * Inserts the comments from JSON into a single file.
+ */
+void _convertFile(File file, Map<String,List<String>> comments) {

[Bob Nystrom, 2012/11/26 22:00:19]

Nit, space after ",".

[Andrei Mouravski, 2012/11/27 03:11:45]

Done.

+  var fileLines = file.readAsLinesSync();
+
+  var unusedComments = {};
+
+  comments.forEach((key, comments) {
+    var index = fileLines.indexOf(key);
+    // If the key is found in any line past the first one.
+    if (index > 0 && fileLines[index - 1].trim().startsWith('///') &&
+      fileLines[index - 1].contains('@docsEditable')) {
+
+      // Add comments.

[Bob Nystrom, 2012/11/26 22:00:19]

Do you need to worry about removing the previous comment from there?

[Andrei Mouravski, 2012/11/27 03:11:45]

No.

+      fileLines.insertRange(index - 1, comments.length);
+      fileLines.setRange(index - 1, comments.length, comments);
+    } else {
+      unusedComments.putIfAbsent(key, () => comments);
+    }
+  });
+
+  unusedComments.forEach((String key, _) {
+    print('WARNING: the following key was found in the JSON but not in '
+        '${new Path(file.fullPathSync()).filename}:\n"$key"');
+    _anyErrors = true;
+  });
+
+  var outputStream = file.openOutputStream();

[Bob Nystrom, 2012/11/26 22:00:19]

file.writeAtStringSync(Strings.join(fileLines, '\n'));

[Andrei Mouravski, 2012/11/27 03:11:45]

WriteAsString not in trunk yet.

+  outputStream.writeString(Strings.join(fileLines, '\n'));
+}