don't print ellipsis if thing is inherited
Closes #849
Squashed commit of the following:
commit 1ec615881f599d7ba9c3453184806d53a94139a1
Author: Seth Ladd <sethladd@google.com>
Date: Fri Aug 21 16:45:27 2015 -0700
don't print ellipsis if thing is inherited
commit 2ced991706f5283c66083529c5deae79736cfca8
Author: Seth Ladd <sethladd@google.com>
Date: Fri Aug 21 16:43:50 2015 -0700
don't print an ellipsis of method is inherited
commit 1ba738d15321f152b780566cc97b2c1dfd103d12
Author: Seth Ladd <sethladd@google.com>
Date: Fri Aug 21 16:31:50 2015 -0700
add ellipsis when there's more beyond a one-liner
diff --git a/lib/markdown_processor.dart b/lib/markdown_processor.dart
index d265368..16a4493 100644
--- a/lib/markdown_processor.dart
+++ b/lib/markdown_processor.dart
@@ -47,6 +47,7 @@
}
}
+// TODO: this is in the wrong place
class Documentation {
final ModelElement element;
String _asHtml;
@@ -65,6 +66,8 @@
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 f41416d..32f20b5 100644
--- a/lib/src/html_generator.dart
+++ b/lib/src/html_generator.dart
@@ -80,6 +80,8 @@
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<String> partials = [
'callable',
'callable_multiline',
@@ -94,7 +96,8 @@
'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 7f08b7a..efd3d4e 100644
--- a/lib/src/model.dart
+++ b/lib/src/model.dart
@@ -62,13 +62,23 @@
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 @@
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 @@
String get kind => 'dynamic';
}
-class Package implements Nameable {
+class Package implements Nameable, Documentable {
final List<Library> _libraries = [];
final PackageMeta packageMeta;
String _docsAsHtml;
@@ -425,6 +439,9 @@
return _docsAsHtml;
}
+ // TODO: make this work
+ bool get hasMoreThanOneLineDocs => true;
+
List<Library> get libraries => _libraries;
Package(Iterable<LibraryElement> libraryElements, this.packageMeta) {
@@ -1307,7 +1324,7 @@
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 @@
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 f28c7d8..51d57b6 100644
--- a/lib/templates/_callable.html
+++ b/lib/templates/_callable.html
@@ -8,5 +8,5 @@
{{#isInherited}}
<div class="features">inherited</div>
{{/isInherited}}
- <p>{{{ oneLineDoc }}}</p>
+ <p>{{{ oneLineDoc }}}{{^isInherited}}{{>has_more_docs}}{{/isInherited}}</p>
</dd>
diff --git a/lib/templates/_constant.html b/lib/templates/_constant.html
index 1e809e8..1fba6cc 100644
--- a/lib/templates/_constant.html
+++ b/lib/templates/_constant.html
@@ -5,5 +5,5 @@
</dt>
<dd>
<div class="features">const</div>
- <p>{{{ oneLineDoc }}}</p>
+ <p>{{{ oneLineDoc }}}{{>has_more_docs}}</p>
</dd>
diff --git a/lib/templates/_has_more_docs.html b/lib/templates/_has_more_docs.html
new file mode 100644
index 0000000..0678a72
--- /dev/null
+++ b/lib/templates/_has_more_docs.html
@@ -0,0 +1,3 @@
+{{#hasMoreThanOneLineDocs}}
+<a href="{{href}}">…</a>
+{{/hasMoreThanOneLineDocs}}
diff --git a/lib/templates/_property.html b/lib/templates/_property.html
index a99f836..e97ad59 100644
--- a/lib/templates/_property.html
+++ b/lib/templates/_property.html
@@ -5,5 +5,5 @@
</dt>
<dd>
{{>readable_writable}}
- <p>{{{ oneLineDoc }}}</p>
+ <p>{{{ oneLineDoc }}}{{^isInherited}}{{>has_more_docs}}{{/isInherited}}</p>
</dd>
diff --git a/lib/templates/class.html b/lib/templates/class.html
index 0c54a8f..3950531 100644
--- a/lib/templates/class.html
+++ b/lib/templates/class.html
@@ -131,7 +131,7 @@
const
</div>
{{/isConst}}
- <p>{{{ oneLineDoc }}}</p>
+ <p>{{{ oneLineDoc }}}{{>has_more_docs}}</p>
</dd>
{{/clazz.constructors}}
</dl>
diff --git a/lib/templates/index.html b/lib/templates/index.html
index 1819de9..d37badc 100644
--- a/lib/templates/index.html
+++ b/lib/templates/index.html
@@ -26,7 +26,10 @@
</dt>
<dd>
{{#isNotDocumented}}<span class="undocumented">Library not documented.</span>{{/isNotDocumented}}
- <p>{{{ oneLineDoc }}}</p>
+ <p>
+ {{{ oneLineDoc }}}
+ {{>has_more_docs}}
+ </p>
</dd>
{{/package.libraries}}
</dl>
diff --git a/lib/templates/library.html b/lib/templates/library.html
index 6c77adb..681d0a1 100644
--- a/lib/templates/library.html
+++ b/lib/templates/library.html
@@ -77,7 +77,7 @@
{{{linkedName}}}
</dt>
<dd>
- <p>{{{ oneLineDoc }}}</p>
+ <p>{{{ oneLineDoc }}}{{>has_more_docs}}</p>
</dd>
{{/library.enums}}
</dl>
@@ -94,7 +94,7 @@
<span class="name {{#isDeprecated}}deprecated{{/isDeprecated}}">{{{linkedName}}}</span>
</dt>
<dd>
- <p>{{{ oneLineDoc }}}</p>
+ <p>{{{ oneLineDoc }}}{{>has_more_docs}}</p>
</dd>
{{/library.classes}}
</dl>
@@ -111,7 +111,7 @@
<span class="name {{#isDeprecated}}deprecated{{/isDeprecated}}">{{{linkedName}}}</span>
</dt>
<dd>
- <p>{{{ oneLineDoc }}}</p>
+ <p>{{{ oneLineDoc }}}{{>has_more_docs}}</p>
</dd>
{{/library.exceptions}}
</dl>
diff --git a/test/model_test.dart b/test/model_test.dart
index 051b446..0e828ca 100644
--- a/test/model_test.dart
+++ b/test/model_test.dart
@@ -116,21 +116,33 @@
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\'` <cool>');
});
+ test('has one line docs', () {
+ expect(
+ fakeLibrary.oneLineDoc,
+ equals(
+ 'WOW FAKE PACKAGE IS <strong>BEST</strong> <a href="http://example.org">PACKAGE</a>'));
+ });
+
+ test('has more than one line docs (or not)', () {
+ expect(fakeLibrary.hasMoreThanOneLineDocs, true);
+ expect(exLibrary.hasMoreThanOneLineDocs, false);
+ });
+
test('has properties', () {
expect(exLibrary.hasProperties, isTrue);
});
