diff --git a/lib/markdown_processor.dart b/lib/markdown_processor.dart index d26536833b..16a4493c4b 100644 --- a/lib/markdown_processor.dart +++ b/lib/markdown_processor.dart @@ -47,6 +47,7 @@ String _linkDocReference(String reference, ModelElement element, } } +// TODO: this is in the wrong place class Documentation { final ModelElement element; String _asHtml; @@ -65,6 +66,8 @@ class Documentation { String get asOneLiner => _asOneLiner; + bool get hasMoreThanOneLineDocs => _asHtmlDocument.body.children.length > 1; + void _processDocsAsMarkdown() { String tempHtml = renderMarkdownToHtml(raw, element); _asHtmlDocument = parse(tempHtml); diff --git a/lib/src/html_generator.dart b/lib/src/html_generator.dart index f41416ddf1..32f20b55fc 100644 --- a/lib/src/html_generator.dart +++ b/lib/src/html_generator.dart @@ -80,6 +80,8 @@ class Templates { topLevelPropertyTemplate = await _loadTemplate('top_level_property.html'); typeDefTemplate = await _loadTemplate('typedef.html'); + // TODO: if we can ever enumerate the contents of a package, we + // won't need this. List partials = [ 'callable', 'callable_multiline', @@ -94,7 +96,8 @@ class Templates { 'sidebar_for_class', 'source_code', 'sidebar_for_library', - 'name_link' + 'name_link', + 'has_more_docs' ]; for (String partial in partials) { diff --git a/lib/src/model.dart b/lib/src/model.dart index 7f08b7ab2f..efd3d4ef06 100644 --- a/lib/src/model.dart +++ b/lib/src/model.dart @@ -62,13 +62,23 @@ abstract class Nameable { String get name; } -abstract class ModelElement implements Comparable, Nameable { +/// Bridges the gap between model elements and packages, +/// both of which have documentation. +abstract class Documentable { + String get oneLineDoc; + String get documentation; + String get documentationAsHtml; + bool get hasMoreThanOneLineDocs; + bool get hasDocumentation; +} + +abstract class ModelElement implements Comparable, Nameable, Documentable { final Element element; final Library library; ElementType _modelType; String _rawDocs; - Documentation _documentation; + Documentation __documentation; List _parameters; // WARNING: putting anything into the body of this seems @@ -150,20 +160,24 @@ abstract class ModelElement implements Comparable, Nameable { return _rawDocs; } + Documentation get _documentation { + if (__documentation != null) return __documentation; + __documentation = new Documentation(this); + return __documentation; + } + + @override bool get hasDocumentation => documentation != null && documentation.isNotEmpty; - String get documentationAsHtml { - if (_documentation != null) return _documentation.asHtml; - _documentation = new Documentation(this); - return _documentation.asHtml; - } + @override + String get documentationAsHtml => _documentation.asHtml; - String get oneLineDoc { - if (_documentation != null) return _documentation.asOneLiner; - _documentation = new Documentation(this); - return _documentation.asOneLiner; - } + @override + String get oneLineDoc => _documentation.asOneLiner; + + @override + bool get hasMoreThanOneLineDocs => _documentation.hasMoreThanOneLineDocs; String get htmlId => name; @@ -392,7 +406,7 @@ class Dynamic extends ModelElement { String get kind => 'dynamic'; } -class Package implements Nameable { +class Package implements Nameable, Documentable { final List _libraries = []; final PackageMeta packageMeta; String _docsAsHtml; @@ -425,6 +439,9 @@ class Package implements Nameable { return _docsAsHtml; } + // TODO: make this work + bool get hasMoreThanOneLineDocs => true; + List get libraries => _libraries; Package(Iterable libraryElements, this.packageMeta) { @@ -1307,7 +1324,7 @@ class Typedef extends ModelElement implements EnclosedElement { String get _href => '${library.dirName}/$fileName'; } -// TODO: rename this to property +// TODO: rename this to Property class Field extends ModelElement with GetterSetterCombo implements EnclosedElement { @@ -1618,8 +1635,13 @@ abstract class GetterSetterCombo { if (buffer.isNotEmpty) return buffer.toString(); // TODO: check that we'd ever get here. Doesn't seem like we would. + // This is old. return computeDocumentationComment(); } + + String get getterDocsAsHtml => ''; + + String get setterDocsAsHtml => ''; } /// Top-level variables. But also picks up getters and setters? diff --git a/lib/templates/_callable.html b/lib/templates/_callable.html index f28c7d8f9a..51d57b6c2b 100644 --- a/lib/templates/_callable.html +++ b/lib/templates/_callable.html @@ -8,5 +8,5 @@ {{#isInherited}}
inherited
{{/isInherited}} -

{{{ oneLineDoc }}}

+

{{{ oneLineDoc }}}{{^isInherited}}{{>has_more_docs}}{{/isInherited}}

diff --git a/lib/templates/_constant.html b/lib/templates/_constant.html index 1e809e881a..1fba6ccfaa 100644 --- a/lib/templates/_constant.html +++ b/lib/templates/_constant.html @@ -5,5 +5,5 @@
const
-

{{{ oneLineDoc }}}

+

{{{ oneLineDoc }}}{{>has_more_docs}}

diff --git a/lib/templates/_has_more_docs.html b/lib/templates/_has_more_docs.html new file mode 100644 index 0000000000..0678a72d3c --- /dev/null +++ b/lib/templates/_has_more_docs.html @@ -0,0 +1,3 @@ +{{#hasMoreThanOneLineDocs}} +… +{{/hasMoreThanOneLineDocs}} diff --git a/lib/templates/_property.html b/lib/templates/_property.html index a99f836143..e97ad59757 100644 --- a/lib/templates/_property.html +++ b/lib/templates/_property.html @@ -5,5 +5,5 @@
{{>readable_writable}} -

{{{ oneLineDoc }}}

+

{{{ oneLineDoc }}}{{^isInherited}}{{>has_more_docs}}{{/isInherited}}

diff --git a/lib/templates/class.html b/lib/templates/class.html index 0c54a8f770..395053106e 100644 --- a/lib/templates/class.html +++ b/lib/templates/class.html @@ -131,7 +131,7 @@

Constructors

const {{/isConst}} -

{{{ oneLineDoc }}}

+

{{{ oneLineDoc }}}{{>has_more_docs}}

{{/clazz.constructors}} diff --git a/lib/templates/index.html b/lib/templates/index.html index 1819de9fe8..d37badceae 100644 --- a/lib/templates/index.html +++ b/lib/templates/index.html @@ -26,7 +26,10 @@

Libraries

{{#isNotDocumented}}Library not documented.{{/isNotDocumented}} -

{{{ oneLineDoc }}}

+

+ {{{ oneLineDoc }}} + {{>has_more_docs}} +

{{/package.libraries}} diff --git a/lib/templates/library.html b/lib/templates/library.html index 6c77adb7f6..681d0a1044 100644 --- a/lib/templates/library.html +++ b/lib/templates/library.html @@ -77,7 +77,7 @@

Enums

{{{linkedName}}}
-

{{{ oneLineDoc }}}

+

{{{ oneLineDoc }}}{{>has_more_docs}}

{{/library.enums}} @@ -94,7 +94,7 @@

Classes

{{{linkedName}}}
-

{{{ oneLineDoc }}}

+

{{{ oneLineDoc }}}{{>has_more_docs}}

{{/library.classes}} @@ -111,7 +111,7 @@

Exceptions / Errors

{{{linkedName}}}
-

{{{ oneLineDoc }}}

+

{{{ oneLineDoc }}}{{>has_more_docs}}

{{/library.exceptions}} diff --git a/test/model_test.dart b/test/model_test.dart index 051b446db0..0e828cae1c 100644 --- a/test/model_test.dart +++ b/test/model_test.dart @@ -116,21 +116,33 @@ void main() { expect(dartAsyncLib.name, 'dart:async'); }); - test('name', () { + test('has a name', () { expect(exLibrary.name, 'ex'); }); - test('sdk library names', () { + test('sdk library have formatted names', () { expect(dartAsyncLib.name, 'dart:async'); expect(dartAsyncLib.dirName, 'dart-async'); expect(dartAsyncLib.href, 'dart-async/dart-async-library.html'); }); - test('documentation', () { + test('has documentation', () { expect(exLibrary.documentation, 'a library. testing string escaping: `var s = \'a string\'` '); }); + test('has one line docs', () { + expect( + fakeLibrary.oneLineDoc, + equals( + 'WOW FAKE PACKAGE IS BEST PACKAGE')); + }); + + test('has more than one line docs (or not)', () { + expect(fakeLibrary.hasMoreThanOneLineDocs, true); + expect(exLibrary.hasMoreThanOneLineDocs, false); + }); + test('has properties', () { expect(exLibrary.hasProperties, isTrue); });