Support tables in dartdoc (#1557)

* Add type parameters for constructors

* And make navigation consistently include generic types in the class.

* Update test package docs post-merge

* Make dartdoc more like GFM with new markdown package

Author: jcollins-g

lib/src/markdown_processor.dart

@@ -145,7 +145,10 @@ final HtmlEscape htmlEscape = const HtmlEscape(HtmlEscapeMode.ELEMENT);
 final List<md.InlineSyntax> _markdown_syntaxes = [
   new _InlineCodeSyntax(),
   new _AutolinkWithoutScheme()
-];
+]..addAll(md.ExtensionSet.gitHub.inlineSyntaxes);
+
+final List<md.BlockSyntax> _markdown_block_syntaxes = []
+  ..addAll(md.ExtensionSet.gitHub.blockSyntaxes);
 
 // Remove these schemas from the display text for hyperlinks.
 final RegExp _hide_schemes = new RegExp('^(http|https)://');
@@ -984,7 +987,9 @@ class Documentation {
     String text = _element.documentation;
     _showWarningsForGenericsOutsideSquareBracketsBlocks(text, _element);
     MarkdownDocument document = new MarkdownDocument(
-        inlineSyntaxes: _markdown_syntaxes, linkResolver: _linkResolver);
+        inlineSyntaxes: _markdown_syntaxes,
+        blockSyntaxes: _markdown_block_syntaxes,
+        linkResolver: _linkResolver);
     List<String> lines = text.replaceAll('\r\n', '\n').split('\n');
     return document.renderLinesToHtml(lines, processFullDocs);
   }

lib/src/model.dart

@@ -1133,7 +1133,8 @@ class Constructor extends ModelElement
 
   @override
   // TODO(jcollins-g): Revisit this when dart-lang/sdk#31517 is implemented.
-  List<TypeParameter> get typeParameters => (enclosingElement as Class).typeParameters;
+  List<TypeParameter> get typeParameters =>
+      (enclosingElement as Class).typeParameters;
 
   @override
   ModelElement get enclosingElement =>
@@ -1184,7 +1185,8 @@ class Constructor extends ModelElement
       if (constructorName.isEmpty) {
         _nameWithGenerics = '${enclosingElement.name}${genericParameters}';
       } else {
-        _nameWithGenerics = '${enclosingElement.name}${genericParameters}.$constructorName';
+        _nameWithGenerics =
+            '${enclosingElement.name}${genericParameters}.$constructorName';
       }
     }
     return _nameWithGenerics;

pubspec.lock

@@ -144,7 +144,7 @@ packages:
       name: markdown
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "0.11.4"
+    version: "1.0.0"
   matcher:
     description:
       name: matcher

pubspec.yaml

@@ -17,7 +17,7 @@ dependencies:
   # least version 3.0.3 to work around an issue with 3.0.2.
   http_parser: '>=3.0.3 <4.0.0'
   logging: ^0.11.3+1
-  markdown: ^0.11.2
+  markdown: ^1.0.0
   mustache4dart: ^2.1.0
   package_config: '>=0.1.5 <2.0.0'
   path: ^1.3.0

test/model_test.dart

@@ -418,6 +418,36 @@ void main() {
       short = fakeLibrary.functions.firstWhere((f) => f.name == 'short');
     });
 
+    group('markdown extensions', () {
+      Class DocumentWithATable;
+      String docsAsHtml;
+
+      setUp(() {
+        DocumentWithATable = fakeLibrary.classes
+            .firstWhere((cls) => cls.name == 'DocumentWithATable');
+        docsAsHtml = DocumentWithATable.documentationAsHtml;
+      });
+
+      test('Verify table appearance', () {
+        expect(docsAsHtml.contains('<table><thead><tr><th>Component</th>'),
+            isTrue);
+      });
+
+      test('Verify links inside of table headers', () {
+        expect(
+            docsAsHtml.contains(
+                '<th><a href="fake/Annotation-class.html">Annotation</a></th>'),
+            isTrue);
+      });
+
+      test('Verify links inside of table body', () {
+        expect(
+            docsAsHtml.contains(
+                '<tbody><tr><td><a href="fake/DocumentWithATable/foo-constant.html">foo</a></td>'),
+            isTrue);
+      });
+    });
+
     group('doc references', () {
       String docsAsHtml;
 
@@ -1863,9 +1893,8 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
           exLibrary.constants.firstWhere((c) => c.name == 'deprecated');
       Class Dog = exLibrary.allClasses.firstWhere((c) => c.name == 'Dog');
       aStaticConstField =
-              Dog.allFields.firstWhere((f) => f.name == 'aStaticConstField');
-      aName =
-          Dog.allFields.firstWhere((f) => f.name == 'aName');
+          Dog.allFields.firstWhere((f) => f.name == 'aStaticConstField');
+      aName = Dog.allFields.firstWhere((f) => f.name == 'aName');
     });
 
     test('substrings of the constant values type are not linked (#1535)', () {
@@ -1903,8 +1932,7 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
     });
 
     test('MY_CAT is not linked', () {
-      expect(cat.constantValue,
-          'const ConstantCat(&#39;tabby&#39;)');
+      expect(cat.constantValue, 'const ConstantCat(&#39;tabby&#39;)');
     });
 
     test('exported property', () {
@@ -1920,21 +1948,24 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
     setUp(() {
       apple = exLibrary.classes.firstWhere((c) => c.name == 'Apple');
       constCat = exLibrary.classes.firstWhere((c) => c.name == 'ConstantCat');
-      constructorTester = fakeLibrary.classes.firstWhere((c) => c.name == 'ConstructorTester');
+      constructorTester =
+          fakeLibrary.classes.firstWhere((c) => c.name == 'ConstructorTester');
       constCatConstructor = constCat.constructors[0];
       appleDefaultConstructor =
           apple.constructors.firstWhere((c) => c.name == 'Apple');
       appleConstructorFromString =
           apple.constructors.firstWhere((c) => c.name == 'Apple.fromString');
-      constructorTesterDefault =
-          constructorTester.constructors.firstWhere((c) => c.name == 'ConstructorTester');
-      constructorTesterFromSomething =
-          constructorTester.constructors.firstWhere((c) => c.name == 'ConstructorTester.fromSomething');
+      constructorTesterDefault = constructorTester.constructors
+          .firstWhere((c) => c.name == 'ConstructorTester');
+      constructorTesterFromSomething = constructorTester.constructors
+          .firstWhere((c) => c.name == 'ConstructorTester.fromSomething');
     });
 
     test('displays generic parameters correctly', () {
-      expect(constructorTesterDefault.nameWithGenerics, 'ConstructorTester&lt;A, B&gt;');
-      expect(constructorTesterFromSomething.nameWithGenerics, 'ConstructorTester&lt;A, B&gt;.fromSomething');
+      expect(constructorTesterDefault.nameWithGenerics,
+          'ConstructorTester&lt;A, B&gt;');
+      expect(constructorTesterFromSomething.nameWithGenerics,
+          'ConstructorTester&lt;A, B&gt;.fromSomething');
     });
 
     test('has a fully qualified name', () {

test/src/utils.dart

@@ -66,4 +66,4 @@ Package bootBasicPackage(
           true,
           withAutoIncludedDependencies)
       .buildPackage();
-}
+}

testing/test_package/lib/fake.dart

@@ -92,6 +92,42 @@ class HasGenerics<X, Y, Z> {
   Map<X, Y> convertToMap() => null;
 }
 
+
+/// This is a class with a table.
+///
+/// It has multiple sentences before the table.  Because testing is a good
+/// idea.
+///
+/// | Component | Symbol | Short Form   | Long Form         | Numeric   | 2-digit   |
+/// |-----------|:------:|--------------|-------------------|-----------|-----------|
+/// | era       |   G    | G (AD)       | GGGG (Anno Domini)| -         | -         |
+/// | year      |   y    | -            | -                 | y (2015)  | yy (15)   |
+/// | month     |   M    | MMM (Sep)    | MMMM (September)  | M (9)     | MM (09)   |
+/// | day       |   d    | -            | -                 | d (3)     | dd (03)   |
+/// | weekday   |   E    | EEE (Sun)    | EEEE (Sunday)     | -         | -         |
+/// | hour      |   j    | -            | -                 | j (13)    | jj (13)   |
+/// | hour12    |   h    | -            | -                 | h (1 PM)  | hh (01 PM)|
+/// | hour24    |   H    | -            | -                 | H (13)    | HH (13)   |
+/// | minute    |   m    | -            | -                 | m (5)     | mm (05)   |
+/// | second    |   s    | -            | -                 | s (9)     | ss (09)   |
+/// | timezone  |   z    | -            | z (Pacific Standard Time)| -  | -         |
+/// | timezone  |   Z    | Z (GMT-8:00) | -                 | -         | -         |
+///
+/// It also has a short table with embedded links.
+///
+/// | [DocumentWithATable] | [Annotation] | [aMethod] |
+/// |----------------------|--------------|-----------|
+/// | [foo]                | Not really   | "blah"    |
+/// | [bar]                | Maybe        | "stuff"   |
+class DocumentWithATable {
+  static const DocumentWithATable foo = const DocumentWithATable();
+  static const DocumentWithATable bar = const DocumentWithATable();
+
+  const DocumentWithATable();
+  void aMethod(String parameter) {}
+}
+
+
 Map<dynamic, String> mapWithDynamicKeys = {};
 
 /// Useful for annotations.

testing/test_package_docs/fake/AClassUsingASuperMixin-class.html

@@ -50,6 +50,7 @@ <h5>library fake</h5>
       <li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
       <li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
       <li><a href="fake/Cool-class.html">Cool</a></li>
+      <li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
       <li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
       <li><a href="fake/Foo2-class.html">Foo2</a></li>
       <li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

testing/test_package_docs/fake/AMixinCallingSuper-class.html

@@ -50,6 +50,7 @@ <h5>library fake</h5>
       <li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
       <li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
       <li><a href="fake/Cool-class.html">Cool</a></li>
+      <li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
       <li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
       <li><a href="fake/Foo2-class.html">Foo2</a></li>
       <li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

testing/test_package_docs/fake/Annotation-class.html

@@ -50,6 +50,7 @@ <h5>library fake</h5>
       <li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
       <li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
       <li><a href="fake/Cool-class.html">Cool</a></li>
+      <li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
       <li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
       <li><a href="fake/Foo2-class.html">Foo2</a></li>
       <li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>