Lots of stuff hooking up markdown to dartdoc.

utils/markdown/block_parser.dart

 // Copyright (c) 2011, 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.
 
 /// The line contains only whitespace or is empty.
 final _RE_EMPTY = const RegExp(@'^([ \t]*)$');
 
-/// A series of "=" or "-" (on the next line) define setext-style headers.
+/// A series of `=` or `-` (on the next line) define setext-style headers.
 final _RE_SETEXT = const RegExp(@'^((=+)|(-+))$');
 
-/// Leading (and trailing) "#" define atx-style headers.
+/// Leading (and trailing) `#` define atx-style headers.
 final _RE_HEADER = const RegExp(@'^(#{1,6})(.*?)#*$');
 
-/// The line starts with ">" with one optional space after.
+/// The line starts with `>` with one optional space after.
 final _RE_BLOCKQUOTE = const RegExp(@'^[ ]{0,3}>[ ]?(.*)$');
 
 /// A line indented four spaces. Used for code blocks and lists.
 final _RE_INDENT = const RegExp(@'^(?:    |\t)(.*)$');
 
 /// Three or more hyphens, asterisks or underscores by themselves. Note that
-/// a line like "----" is valid as both HR and SETEXT. In case of a tie,
+/// a line like `----` is valid as both HR and SETEXT. In case of a tie,
 /// SETEXT should win.
 final _RE_HR = const RegExp(@'^[ ]{0,3}((-+[ ]{0,2}){3,}|' +
                                  @'(_+[ ]{0,2}){3,}|' +
                                  @'(\*+[ ]{0,2}){3,})$');
 
 /// Really hacky way to detect block-level embedded HTML. Just looks for
 /// "<somename".
 final _RE_HTML = const RegExp(@'^<[ ]*\w+[ >]');
 
-/// A line starting with one of these markers: "-", "*", "+". May have up to
+/// A line starting with one of these markers: `-`, `*`, `+`. May have up to
 /// three leading spaces before the marker and any number of spaces or tabs
 /// after.
 final _RE_UL = const RegExp(@'^[ ]{0,3}[*+-][ \t]+(.*)$');
 
-/// A line starting with a number like "123.". May have up to three leading
+/// A line starting with a number like `123.`. May have up to three leading
 /// spaces before the marker and any number of spaces or tabs after.
 final _RE_OL = const RegExp(@'^[ ]{0,3}\d+\.[ \t]+(.*)$');
 
 /// Maintains the internal state needed to parse a series of lines into blocks
 /// of markdown suitable for further inline parsing.
 class BlockParser {
   final List<String> lines;
 
   /// The markdown document this parser is parsing.
   final Document document;
 
   /// Index of the current line.
   int pos;
 
   BlockParser(this.lines, this.document)
     : pos = 0;
 
   /// Gets the current line.
   String get current() => lines[pos];
 
   /// Gets the line after the current one or `null` if there is none.
   String get next() {
     // Don't read past the end.
     if (pos >= lines.length - 1) return null;
     return lines[pos + 1];
   }
 
-  void advance() => pos++;
+  void advance() {
+    pos++;
+  }
+
   bool get isDone() => pos >= lines.length;
 
   /// Gets whether or not the current line matches the given pattern.
   bool matches(RegExp regex) {
     if (isDone) return false;
     return regex.firstMatch(current) != null;
   }
 
   /// Gets whether or not the current line matches the given pattern.
   bool matchesNext(RegExp regex) {
@@ skipping 31 matching lines @@
   RegExp get pattern() => null;
 
   bool get canEndBlock() => true;
 
   bool canParse(BlockParser parser) {
     return pattern.firstMatch(parser.current) != null;
   }
 
   abstract Node parse(BlockParser parser);
 
-  List<Node> parseChildLines(BlockParser parser) {
+  List<String> parseChildLines(BlockParser parser) {
     // Grab all of the lines that form the blockquote, stripping off the ">".
-    final childLines = [];
+    final childLines = <String>[];
 
     while (!parser.isDone) {
       final match = pattern.firstMatch(parser.current);
       if (match == null) break;
       childLines.add(match.group(1));
       parser.advance();
     }
 
     return childLines;
   }
@@ skipping 29 matching lines @@
 
     final tag = (match.group(1)[0] == '=') ? 'h1' : 'h2';
     final contents = parser.document.parseInline(parser.current);
     parser.advance();
     parser.advance();
 
     return new Element(tag, contents);
   }
 }
 
-/// Parses atx-style headers: "## Header ##".
+/// Parses atx-style headers: `## Header ##`.
 class HeaderSyntax extends BlockSyntax {
   RegExp get pattern() => _RE_HEADER;
 
   Node parse(BlockParser parser) {
     final match = pattern.firstMatch(parser.current);
     parser.advance();
     final level = match.group(1).length;
     final contents = parser.document.parseInline(match.group(2).trim());
     return new Element('h$level', contents);
   }
 }
 
-/// Parses email-style blockquotes: "> quote".
+/// Parses email-style blockquotes: `> quote`.
 class BlockquoteSyntax extends BlockSyntax {
   RegExp get pattern() => _RE_BLOCKQUOTE;
 
   Node parse(BlockParser parser) {
     final childLines = parseChildLines(parser);
 
     // Recursively parse the contents of the blockquote.
     final children = parser.document.parseLines(childLines);
 
     return new Element('blockquote', children);
@@ skipping 10 matching lines @@
     // The Markdown tests expect a trailing newline.
     childLines.add('');
 
     // Escape the code.
     final escaped = escapeHtml(Strings.join(childLines, '\n'));
 
     return new Element('pre', [new Element.text('code', escaped)]);
   }
 }
 
-/// Parses horizontal rules like "---", "_ _ _", "*  *  *", etc.
+/// Parses horizontal rules like `---`, `_ _ _`, `*  *  *`, etc.
 class HorizontalRuleSyntax extends BlockSyntax {
   RegExp get pattern() => _RE_HR;
 
   Node parse(BlockParser parser) {
     final match = pattern.firstMatch(parser.current);
     parser.advance();
     return new Element.empty('hr');
   }
 }
 
 /// Parses inline HTML at the block level. This differs from other markdown
 /// implementations in several ways:
 ///
 /// 1.  This one is way way WAY simpler.
-/// 2.  All HTML tags at the block level will be treated as blocks. If you start
-///     a paragraph with <em>, it will not wrap it in a <p> for you. As soon as
-///     it sees something like HTML, it stops mucking with it until it hits the
-///     next block.
+/// 2.  All HTML tags at the block level will be treated as blocks. If you
+///     start a paragraph with `<em>`, it will not wrap it in a `<p>` for you.
+///     As soon as it sees something like HTML, it stops mucking with it until
+///     it hits the next block.
 /// 3.  Absolutely no HTML parsing or validation is done. We're a markdown
 ///     parser not an HTML parser!
 class BlockHtmlSyntax extends BlockSyntax {
   RegExp get pattern() => _RE_HTML;
 
   bool get canEndBlock() => false;
 
   Node parse(BlockParser parser) {
     final childLines = [];
 
@@ skipping 183 matching lines @@
     while (!isAtBlockEnd(parser)) {
       childLines.add(parser.current);
       parser.advance();
     }
 
     final contents = parser.document.parseInline(
         Strings.join(childLines, '\n'));
     return new Element('p', contents);
   }
 }