Skip to content

Commit cc9b95a

Browse files
jcollins-gjcollins-g
authored
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
1 parent ce4284c commit cc9b95a

File tree

91 files changed

+1490
-19
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

91 files changed

+1490
-19
lines changed

‎lib/src/markdown_processor.dart

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,10 @@ final HtmlEscape htmlEscape = const HtmlEscape(HtmlEscapeMode.ELEMENT);
145145
final List<md.InlineSyntax> _markdown_syntaxes = [
146146
new _InlineCodeSyntax(),
147147
new _AutolinkWithoutScheme()
148-
];
148+
]..addAll(md.ExtensionSet.gitHub.inlineSyntaxes);
149+
150+
final List<md.BlockSyntax> _markdown_block_syntaxes = []
151+
..addAll(md.ExtensionSet.gitHub.blockSyntaxes);
149152

150153
// Remove these schemas from the display text for hyperlinks.
151154
final RegExp _hide_schemes = new RegExp('^(http|https)://');
@@ -984,7 +987,9 @@ class Documentation {
984987
String text = _element.documentation;
985988
_showWarningsForGenericsOutsideSquareBracketsBlocks(text, _element);
986989
MarkdownDocument document = new MarkdownDocument(
987-
inlineSyntaxes: _markdown_syntaxes, linkResolver: _linkResolver);
990+
inlineSyntaxes: _markdown_syntaxes,
991+
blockSyntaxes: _markdown_block_syntaxes,
992+
linkResolver: _linkResolver);
988993
List<String> lines = text.replaceAll('\r\n', '\n').split('\n');
989994
return document.renderLinesToHtml(lines, processFullDocs);
990995
}

‎lib/src/model.dart

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1133,7 +1133,8 @@ class Constructor extends ModelElement
11331133

11341134
@override
11351135
// TODO(jcollins-g): Revisit this when dart-lang/sdk#31517 is implemented.
1136-
List<TypeParameter> get typeParameters => (enclosingElement as Class).typeParameters;
1136+
List<TypeParameter> get typeParameters =>
1137+
(enclosingElement as Class).typeParameters;
11371138

11381139
@override
11391140
ModelElement get enclosingElement =>
@@ -1184,7 +1185,8 @@ class Constructor extends ModelElement
11841185
if (constructorName.isEmpty) {
11851186
_nameWithGenerics = '${enclosingElement.name}${genericParameters}';
11861187
} else {
1187-
_nameWithGenerics = '${enclosingElement.name}${genericParameters}.$constructorName';
1188+
_nameWithGenerics =
1189+
'${enclosingElement.name}${genericParameters}.$constructorName';
11881190
}
11891191
}
11901192
return _nameWithGenerics;

‎pubspec.lock

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -144,7 +144,7 @@ packages:
144144
name: markdown
145145
url: "https://pub.dartlang.org"
146146
source: hosted
147-
version: "0.11.4"
147+
version: "1.0.0"
148148
matcher:
149149
description:
150150
name: matcher

‎pubspec.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ dependencies:
1717
# least version 3.0.3 to work around an issue with 3.0.2.
1818
http_parser: '>=3.0.3 <4.0.0'
1919
logging: ^0.11.3+1
20-
markdown: ^0.11.2
20+
markdown: ^1.0.0
2121
mustache4dart: ^2.1.0
2222
package_config: '>=0.1.5 <2.0.0'
2323
path: ^1.3.0

‎test/model_test.dart

Lines changed: 43 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -418,6 +418,36 @@ void main() {
418418
short = fakeLibrary.functions.firstWhere((f) => f.name == 'short');
419419
});
420420

421+
group('markdown extensions', () {
422+
Class DocumentWithATable;
423+
String docsAsHtml;
424+
425+
setUp(() {
426+
DocumentWithATable = fakeLibrary.classes
427+
.firstWhere((cls) => cls.name == 'DocumentWithATable');
428+
docsAsHtml = DocumentWithATable.documentationAsHtml;
429+
});
430+
431+
test('Verify table appearance', () {
432+
expect(docsAsHtml.contains('<table><thead><tr><th>Component</th>'),
433+
isTrue);
434+
});
435+
436+
test('Verify links inside of table headers', () {
437+
expect(
438+
docsAsHtml.contains(
439+
'<th><a href="fake/Annotation-class.html">Annotation</a></th>'),
440+
isTrue);
441+
});
442+
443+
test('Verify links inside of table body', () {
444+
expect(
445+
docsAsHtml.contains(
446+
'<tbody><tr><td><a href="fake/DocumentWithATable/foo-constant.html">foo</a></td>'),
447+
isTrue);
448+
});
449+
});
450+
421451
group('doc references', () {
422452
String docsAsHtml;
423453

@@ -1863,9 +1893,8 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
18631893
exLibrary.constants.firstWhere((c) => c.name == 'deprecated');
18641894
Class Dog = exLibrary.allClasses.firstWhere((c) => c.name == 'Dog');
18651895
aStaticConstField =
1866-
Dog.allFields.firstWhere((f) => f.name == 'aStaticConstField');
1867-
aName =
1868-
Dog.allFields.firstWhere((f) => f.name == 'aName');
1896+
Dog.allFields.firstWhere((f) => f.name == 'aStaticConstField');
1897+
aName = Dog.allFields.firstWhere((f) => f.name == 'aName');
18691898
});
18701899

18711900
test('substrings of the constant values type are not linked (#1535)', () {
@@ -1903,8 +1932,7 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
19031932
});
19041933

19051934
test('MY_CAT is not linked', () {
1906-
expect(cat.constantValue,
1907-
'const ConstantCat(&#39;tabby&#39;)');
1935+
expect(cat.constantValue, 'const ConstantCat(&#39;tabby&#39;)');
19081936
});
19091937

19101938
test('exported property', () {
@@ -1920,21 +1948,24 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
19201948
setUp(() {
19211949
apple = exLibrary.classes.firstWhere((c) => c.name == 'Apple');
19221950
constCat = exLibrary.classes.firstWhere((c) => c.name == 'ConstantCat');
1923-
constructorTester = fakeLibrary.classes.firstWhere((c) => c.name == 'ConstructorTester');
1951+
constructorTester =
1952+
fakeLibrary.classes.firstWhere((c) => c.name == 'ConstructorTester');
19241953
constCatConstructor = constCat.constructors[0];
19251954
appleDefaultConstructor =
19261955
apple.constructors.firstWhere((c) => c.name == 'Apple');
19271956
appleConstructorFromString =
19281957
apple.constructors.firstWhere((c) => c.name == 'Apple.fromString');
1929-
constructorTesterDefault =
1930-
constructorTester.constructors.firstWhere((c) => c.name == 'ConstructorTester');
1931-
constructorTesterFromSomething =
1932-
constructorTester.constructors.firstWhere((c) => c.name == 'ConstructorTester.fromSomething');
1958+
constructorTesterDefault = constructorTester.constructors
1959+
.firstWhere((c) => c.name == 'ConstructorTester');
1960+
constructorTesterFromSomething = constructorTester.constructors
1961+
.firstWhere((c) => c.name == 'ConstructorTester.fromSomething');
19331962
});
19341963

19351964
test('displays generic parameters correctly', () {
1936-
expect(constructorTesterDefault.nameWithGenerics, 'ConstructorTester&lt;A, B&gt;');
1937-
expect(constructorTesterFromSomething.nameWithGenerics, 'ConstructorTester&lt;A, B&gt;.fromSomething');
1965+
expect(constructorTesterDefault.nameWithGenerics,
1966+
'ConstructorTester&lt;A, B&gt;');
1967+
expect(constructorTesterFromSomething.nameWithGenerics,
1968+
'ConstructorTester&lt;A, B&gt;.fromSomething');
19381969
});
19391970

19401971
test('has a fully qualified name', () {

‎test/src/utils.dart

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,4 +66,4 @@ Package bootBasicPackage(
6666
true,
6767
withAutoIncludedDependencies)
6868
.buildPackage();
69-
}
69+
}

‎testing/test_package/lib/fake.dart

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,42 @@ class HasGenerics<X, Y, Z> {
9292
Map<X, Y> convertToMap() => null;
9393
}
9494

95+
96+
/// This is a class with a table.
97+
///
98+
/// It has multiple sentences before the table. Because testing is a good
99+
/// idea.
100+
///
101+
/// | Component | Symbol | Short Form | Long Form | Numeric | 2-digit |
102+
/// |-----------|:------:|--------------|-------------------|-----------|-----------|
103+
/// | era | G | G (AD) | GGGG (Anno Domini)| - | - |
104+
/// | year | y | - | - | y (2015) | yy (15) |
105+
/// | month | M | MMM (Sep) | MMMM (September) | M (9) | MM (09) |
106+
/// | day | d | - | - | d (3) | dd (03) |
107+
/// | weekday | E | EEE (Sun) | EEEE (Sunday) | - | - |
108+
/// | hour | j | - | - | j (13) | jj (13) |
109+
/// | hour12 | h | - | - | h (1 PM) | hh (01 PM)|
110+
/// | hour24 | H | - | - | H (13) | HH (13) |
111+
/// | minute | m | - | - | m (5) | mm (05) |
112+
/// | second | s | - | - | s (9) | ss (09) |
113+
/// | timezone | z | - | z (Pacific Standard Time)| - | - |
114+
/// | timezone | Z | Z (GMT-8:00) | - | - | - |
115+
///
116+
/// It also has a short table with embedded links.
117+
///
118+
/// | [DocumentWithATable] | [Annotation] | [aMethod] |
119+
/// |----------------------|--------------|-----------|
120+
/// | [foo] | Not really | "blah" |
121+
/// | [bar] | Maybe | "stuff" |
122+
class DocumentWithATable {
123+
static const DocumentWithATable foo = const DocumentWithATable();
124+
static const DocumentWithATable bar = const DocumentWithATable();
125+
126+
const DocumentWithATable();
127+
void aMethod(String parameter) {}
128+
}
129+
130+
95131
Map<dynamic, String> mapWithDynamicKeys = {};
96132

97133
/// Useful for annotations.

‎testing/test_package_docs/fake/AClassUsingASuperMixin-class.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ <h5>library fake</h5>
5050
<li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
5151
<li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
5252
<li><a href="fake/Cool-class.html">Cool</a></li>
53+
<li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
5354
<li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
5455
<li><a href="fake/Foo2-class.html">Foo2</a></li>
5556
<li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

‎testing/test_package_docs/fake/AMixinCallingSuper-class.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ <h5>library fake</h5>
5050
<li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
5151
<li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
5252
<li><a href="fake/Cool-class.html">Cool</a></li>
53+
<li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
5354
<li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
5455
<li><a href="fake/Foo2-class.html">Foo2</a></li>
5556
<li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

‎testing/test_package_docs/fake/Annotation-class.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ <h5>library fake</h5>
5050
<li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
5151
<li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
5252
<li><a href="fake/Cool-class.html">Cool</a></li>
53+
<li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
5354
<li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
5455
<li><a href="fake/Foo2-class.html">Foo2</a></li>
5556
<li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

‎testing/test_package_docs/fake/AnotherInterface-class.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ <h5>library fake</h5>
5050
<li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
5151
<li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
5252
<li><a href="fake/Cool-class.html">Cool</a></li>
53+
<li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
5354
<li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
5455
<li><a href="fake/Foo2-class.html">Foo2</a></li>
5556
<li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

‎testing/test_package_docs/fake/BaseForDocComments-class.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ <h5>library fake</h5>
5050
<li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
5151
<li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
5252
<li><a href="fake/Cool-class.html">Cool</a></li>
53+
<li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
5354
<li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
5455
<li><a href="fake/Foo2-class.html">Foo2</a></li>
5556
<li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

‎testing/test_package_docs/fake/BaseThingy-class.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ <h5>library fake</h5>
5050
<li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
5151
<li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
5252
<li><a href="fake/Cool-class.html">Cool</a></li>
53+
<li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
5354
<li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
5455
<li><a href="fake/Foo2-class.html">Foo2</a></li>
5556
<li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

‎testing/test_package_docs/fake/BaseThingy2-class.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ <h5>library fake</h5>
5050
<li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
5151
<li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
5252
<li><a href="fake/Cool-class.html">Cool</a></li>
53+
<li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
5354
<li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
5455
<li><a href="fake/Foo2-class.html">Foo2</a></li>
5556
<li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

‎testing/test_package_docs/fake/CUSTOM_CLASS-constant.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ <h5>library fake</h5>
5050
<li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
5151
<li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
5252
<li><a href="fake/Cool-class.html">Cool</a></li>
53+
<li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
5354
<li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
5455
<li><a href="fake/Foo2-class.html">Foo2</a></li>
5556
<li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

‎testing/test_package_docs/fake/Callback2.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ <h5>library fake</h5>
5050
<li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
5151
<li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
5252
<li><a href="fake/Cool-class.html">Cool</a></li>
53+
<li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
5354
<li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
5455
<li><a href="fake/Foo2-class.html">Foo2</a></li>
5556
<li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

‎testing/test_package_docs/fake/ClassWithUnusualProperties-class.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ <h5>library fake</h5>
5050
<li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
5151
<li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
5252
<li><a href="fake/Cool-class.html">Cool</a></li>
53+
<li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
5354
<li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
5455
<li><a href="fake/Foo2-class.html">Foo2</a></li>
5556
<li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

‎testing/test_package_docs/fake/Color-class.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ <h5>library fake</h5>
5050
<li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
5151
<li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
5252
<li><a href="fake/Cool-class.html">Cool</a></li>
53+
<li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
5354
<li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
5455
<li><a href="fake/Foo2-class.html">Foo2</a></li>
5556
<li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

‎testing/test_package_docs/fake/ConstantClass-class.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ <h5>library fake</h5>
5050
<li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
5151
<li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
5252
<li><a href="fake/Cool-class.html">Cool</a></li>
53+
<li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
5354
<li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
5455
<li><a href="fake/Foo2-class.html">Foo2</a></li>
5556
<li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

‎testing/test_package_docs/fake/ConstructorTester-class.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ <h5>library fake</h5>
5050
<li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
5151
<li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
5252
<li><a href="fake/Cool-class.html">Cool</a></li>
53+
<li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
5354
<li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
5455
<li><a href="fake/Foo2-class.html">Foo2</a></li>
5556
<li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

‎testing/test_package_docs/fake/Cool-class.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ <h5>library fake</h5>
5050
<li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
5151
<li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
5252
<li><a href="fake/Cool-class.html">Cool</a></li>
53+
<li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
5354
<li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
5455
<li><a href="fake/Foo2-class.html">Foo2</a></li>
5556
<li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

‎testing/test_package_docs/fake/DOWN-constant.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ <h5>library fake</h5>
5050
<li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
5151
<li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
5252
<li><a href="fake/Cool-class.html">Cool</a></li>
53+
<li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
5354
<li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>
5455
<li><a href="fake/Foo2-class.html">Foo2</a></li>
5556
<li><a href="fake/HasGenerics-class.html">HasGenerics</a></li>

0 commit comments

Comments
 (0)