Convert /** comments to /// in pub.

tools/line_doc_comments.dart

Index: tools/line_doc_comments.dart
diff --git a/tools/line_doc_comments.dart b/tools/line_doc_comments.dart
new file mode 100755
index 0000000000000000000000000000000000000000..969d690dbf870b9039d47274deba99b47f5ddb5d
--- /dev/null
+++ b/tools/line_doc_comments.dart
@@ -0,0 +1,89 @@
+#!/usr/bin/env dart
+
+/// Converts block-style Doc comments in Dart code to line style.
+library line_doc_comments;
+import 'dart:io';
+
+import '../pkg/path/lib/path.dart' as path;
+
+final oneLineBlock = new RegExp(r'^(\s*)/\*\*\s?(.*)\*/\s*$');
+final startBlock = new RegExp(r'^(\s*)/\*\*(.*)$');
+final blockLine = new RegExp(r'^\s*\*\s?(.*)$');
+final endBlock = new RegExp(r'^\s*\*/\s*$');
+
+main() {
+  var args = new Options().arguments;
+  if (args.length != 1) {
+    print('Converts "/**"-style block doc comments in a directory ');
+    print('containing Dart code to "///"-style line doc comments.');
+    print('');
+    print('Usage: ./line_doc_coments.dart <dir>');

[nweiz, 2012/12/19 20:56:07]

Style nit: I'd ditch the "./" here.

[Bob Nystrom, 2012/12/20 02:04:15]

Done.

+    return;
+  }
+
+  var dir = new Directory(args[0]);
+  var lister = dir.list(recursive: true);
+  lister.onFile = (file) {
+    if (path.extension(file) != '.dart') return;
+    fixFile(file);
+  };
+}
+
+void fixFile(String path) {
+  new File(path).readAsLines().transform(fixContents).chain((fixed) {

[nweiz, 2012/12/19 20:56:07]

Maybe a little cleaner to assign the file to a local var?

[Bob Nystrom, 2012/12/20 02:04:15]

Done.

+    return new File(path).writeAsString(fixed);
+  }).then((file) {
+    print(file.name);
+  });
+}
+
+String fixContents(List<String> lines) {
+  var buffer = new StringBuffer();
+  var inBlock = false;
+  var indent;
+  for (var line in lines) {
+    if (inBlock) {
+      // See if it's the end of the comment.
+      var match = endBlock.firstMatch(line);
+      if (match != null) {

[nweiz, 2012/12/19 20:56:07]

Slightly cleaner to do "if (endBlock.hasMatch(line))", since you never use any
of the match metadata.

[Bob Nystrom, 2012/12/20 02:04:15]

Done.

+        inBlock = false;
+
+        // Just a pointless line, delete it!
+        line = null;
+      } else {
+        match = blockLine.firstMatch(line);
+        line = '$indent/// ${match[1]}';

[nweiz, 2012/12/19 20:56:07]

This will leave trailing whitespace if `match[1]` is empty.

[Bob Nystrom, 2012/12/20 02:04:15]

Done.

+      }
+    } else {
+      // See if it's a one-line block comment like: /** Blah. */
+      var match = oneLineBlock.firstMatch(line);
+      if (match != null) {
+        line = '${match[1]}/// ${match[2]}';
+      } else {
+        // See if it's the start of a block doc comment.
+        match = startBlock.firstMatch(line);
+        if (match != null) {
+          inBlock = true;
+          indent = match[1];
+          if (match[2] != '') {
+            // Got comment on /** line.
+            line = match[2];
+          } else {
+            // Just a pointless line, delete it!
+            line = null;
+          }
+        }
+      }
+    }
+
+    if (line != null) buffer.add('$line\n');
+  }
+
+  return buffer.toString();
+}
+
+match(RegExp regex, String string, callback(List<String> groups)) {

[nweiz, 2012/12/19 20:56:07]

Unused function.

[Bob Nystrom, 2012/12/20 02:04:15]

Done.

+  var result = regex.firstMatch(string);
+  if (result != null) callback(result.groups);
+  return result != null;
+}