Skip to content

Support tables in dartdoc #1557

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Dec 5, 2017
Merged

Support tables in dartdoc #1557

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5dd4a9a
Add type parameters for constructors
jcollins-g Dec 1, 2017
b10167c
And make navigation consistently include generic types in the class.
jcollins-g Dec 1, 2017
08179e8
Merge branch 'master' of github.com:dart-lang/dartdoc into fix-generi…
jcollins-g Dec 4, 2017
b4f30a5
Update test package docs post-merge
jcollins-g Dec 4, 2017
e867366
Make dartdoc more like GFM with new markdown package
jcollins-g Dec 4, 2017
531c0b0
Merge branch 'master' of github.com:dart-lang/dartdoc into fix-generi…
jcollins-g Dec 4, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions lib/src/markdown_processor.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See https://github.com/dart-lang/pub-dartlang-dart/blob/master/app/lib/shared/markdown.dart#L11

Not sure exactly what to do here. Ideally we'd all agree on how markdown is rendered.

https://github.com/dart-lang/pub-dartlang-dart/blob/8ae285f2b846b0e3bf1098162318f6c52eff5776/app/lib/shared/markdown.dart#L11

I've tried to move the markdown package towards GFM standard. But that doesn't include header links.

Just FYI that we've diverged here...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I filed a bug related to this yesterday because markdown's README claims it does have header links for its github extension set: https://github.com/dart-lang/markdown/issues/185.

Dartdoc is always going to have at least a bit of customization, but hopefully we can get it to a point where it is purely additive..


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)://');
Expand Down Expand Up @@ -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);
}
Expand Down
6 changes: 4 additions & 2 deletions lib/src/model.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 =>
Expand Down Expand Up @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion pubspec.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion pubspec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
55 changes: 43 additions & 12 deletions test/model_test.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down Expand Up @@ -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)', () {
Expand Down Expand Up @@ -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', () {
Expand All @@ -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', () {
Expand Down
2 changes: 1 addition & 1 deletion test/src/utils.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,4 +66,4 @@ Package bootBasicPackage(
true,
withAutoIncludedDependencies)
.buildPackage();
}
}
36 changes: 36 additions & 0 deletions testing/test_package/lib/fake.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
1 change: 1 addition & 0 deletions testing/test_package_docs/fake/AClassUsingASuperMixin-class.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
1 change: 1 addition & 0 deletions testing/test_package_docs/fake/AMixinCallingSuper-class.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
1 change: 1 addition & 0 deletions testing/test_package_docs/fake/Annotation-class.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
1 change: 1 addition & 0 deletions testing/test_package_docs/fake/AnotherInterface-class.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
1 change: 1 addition & 0 deletions testing/test_package_docs/fake/BaseForDocComments-class.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
1 change: 1 addition & 0 deletions testing/test_package_docs/fake/BaseThingy-class.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
1 change: 1 addition & 0 deletions testing/test_package_docs/fake/BaseThingy2-class.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
1 change: 1 addition & 0 deletions testing/test_package_docs/fake/CUSTOM_CLASS-constant.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
1 change: 1 addition & 0 deletions testing/test_package_docs/fake/Callback2.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
1 change: 1 addition & 0 deletions testing/test_package_docs/fake/ClassWithUnusualProperties-class.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
1 change: 1 addition & 0 deletions testing/test_package_docs/fake/Color-class.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
1 change: 1 addition & 0 deletions testing/test_package_docs/fake/ConstantClass-class.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
1 change: 1 addition & 0 deletions testing/test_package_docs/fake/ConstructorTester-class.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
1 change: 1 addition & 0 deletions testing/test_package_docs/fake/Cool-class.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
1 change: 1 addition & 0 deletions testing/test_package_docs/fake/DOWN-constant.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
Loading