Skip to content

Commit d72989a

Browse files
jdkorenjdkoren
authored
Move extendedDocLink creation to ModelElementRenderer (#2085)
* Move extendedDocLink creation to ModelElementRenderer * Also separate it from oneLineDoc and update the templates accordingly. * Retain one literal string test * Enum ordinal members do not show extended doc link
1 parent 38d0943 commit d72989a

18 files changed

+49
-40
lines changed

‎lib/src/model/enum.dart

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,14 @@ class EnumField extends Field {
6363
}
6464
}
6565

66+
@override
67+
String get extendedDocLink {
68+
// Ordinal members don't get extended doc links. Inherited members
69+
// (e.g. hashcode) follow the normal rules.
70+
if (index != null) return '';
71+
return super.extendedDocLink;
72+
}
73+
6674
@override
6775
String get href {
6876
if (!identical(canonicalModelElement, this)) {

‎lib/src/model/getter_setter_combo.dart

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,7 @@ mixin GetterSetterCombo on ModelElement {
135135
String get oneLineDoc {
136136
if (_oneLineDoc == null) {
137137
if (!hasAccessorsWithDocs) {
138-
_oneLineDoc = computeOneLineDoc();
138+
_oneLineDoc = super.oneLineDoc;
139139
} else {
140140
StringBuffer buffer = StringBuffer();
141141
if (hasPublicGetter && getter.oneLineDoc.isNotEmpty) {

‎lib/src/model/model_element.dart

Lines changed: 2 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -784,7 +784,7 @@ abstract class ModelElement extends Canonicalization
784784
/// does not exist.
785785
String get extendedDocLink {
786786
if (hasExtendedDocumentation) {
787-
return '<a href="${href}">[...]</a>';
787+
return ModelElementRendererHtml().renderExtendedDocLink(this);
788788
}
789789
return '';
790790
}
@@ -964,19 +964,8 @@ abstract class ModelElement extends Canonicalization
964964
@override
965965
String get name => element.name;
966966

967-
// TODO(jcollins-g): refactor once dartdoc will only run in a VM where mixins
968-
// calling super is allowed (SDK constraint >= 2.1.0).
969-
String computeOneLineDoc() =>
970-
'${_documentation.asOneLiner}${extendedDocLink.isEmpty ? "" : " $extendedDocLink"}';
971-
String _oneLineDoc;
972-
973967
@override
974-
String get oneLineDoc {
975-
if (_oneLineDoc == null) {
976-
_oneLineDoc = computeOneLineDoc();
977-
}
978-
return _oneLineDoc;
979-
}
968+
String get oneLineDoc => _documentation.asOneLiner;
980969

981970
Member get originalMember => _originalMember;
982971

‎lib/src/render/model_element_renderer.dart

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ import 'package:dartdoc/src/model/model_element.dart';
77
abstract class ModelElementRenderer {
88
String renderLinkedName(ModelElement modelElement);
99

10+
String renderExtendedDocLink(ModelElement modelElement);
11+
1012
String renderYoutubeUrl(String youTubeId, String aspectRatio);
1113

1214
String renderAnimation(
@@ -20,6 +22,11 @@ class ModelElementRendererHtml extends ModelElementRenderer {
2022
return '<a${cssClass} href="${modelElement.href}">${modelElement.name}</a>';
2123
}
2224

25+
@override
26+
String renderExtendedDocLink(ModelElement modelElement) {
27+
return '<a href="${modelElement.href}">[...]</a>';
28+
}
29+
2330
@override
2431
String renderYoutubeUrl(String youTubeId, String aspectRatio) {
2532
// Blank lines before and after, and no indenting at the beginning and end

‎lib/templates/_callable.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,6 @@
55
{{>categorization}}
66
</dt>
77
<dd{{ #isInherited }} class="inherited"{{ /isInherited}}>
8-
{{{ oneLineDoc }}}
8+
{{{ oneLineDoc }}} {{{ extendedDocLink }}}
99
{{>features}}
1010
</dd>

‎lib/templates/_class.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,5 @@
22
<span class="name {{#isDeprecated}}deprecated{{/isDeprecated}}">{{{linkedName}}}{{{linkedGenericParameters}}}</span> {{>categorization}}
33
</dt>
44
<dd>
5-
{{{ oneLineDoc }}}
5+
{{{ oneLineDoc }}} {{{ extendedDocLink }}}
66
</dd>

‎lib/templates/_constant.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
{{>categorization}}
55
</dt>
66
<dd>
7-
{{{ oneLineDoc }}}
7+
{{{ oneLineDoc }}} {{{ extendedDocLink }}}
88
{{>features}}
99
<div>
1010
<span class="signature"><code>{{{ constantValueTruncated }}}</code></span>

‎lib/templates/_extension.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22
<span class="name {{#isDeprecated}}deprecated{{/isDeprecated}}">{{{linkedName}}}</span> {{>categorization}}
33
</dt>
44
<dd>
5-
{{{ oneLineDoc }}}
5+
{{{ oneLineDoc }}} {{{ extendedDocLink }}}
66
</dd>
77

‎lib/templates/_library.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,5 @@
22
<span class="name">{{{ linkedName }}}</span> {{>categorization}}
33
</dt>
44
<dd>
5-
{{#isDocumented}}{{{ oneLineDoc }}}{{/isDocumented}}
6-
</dd>
5+
{{#isDocumented}}{{{ oneLineDoc }}} {{{ extendedDocLink }}}{{/isDocumented}}
6+
</dd>

‎lib/templates/_mixin.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,5 @@
22
<span class="name {{#isDeprecated}}deprecated{{/isDeprecated}}">{{{linkedName}}}{{{linkedGenericParameters}}}</span> {{>categorization}}
33
</dt>
44
<dd>
5-
{{{ oneLineDoc }}}
5+
{{{ oneLineDoc }}} {{{ extendedDocLink }}}
66
</dd>

‎lib/templates/_property.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,6 @@
33
<span class="signature">{{{ arrow }}} {{{ linkedReturnType }}}</span> {{>categorization}}
44
</dt>
55
<dd{{ #isInherited }} class="inherited"{{ /isInherited}}>
6-
{{{ oneLineDoc }}}
6+
{{{ oneLineDoc }}} {{{ extendedDocLink }}}
77
{{>features}}
88
</dd>

‎lib/templates/class.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ <h2>Constructors</h2>
8888
<span class="name">{{{linkedName}}}</span><span class="signature">({{{ linkedParams }}})</span>
8989
</dt>
9090
<dd>
91-
{{{ oneLineDoc }}}
91+
{{{ oneLineDoc }}} {{{ extendedDocLink }}}
9292
{{#isConst}}
9393
<div class="constructor-modifier features">const</div>
9494
{{/isConst}}

‎lib/templates/enum.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ <h2>Constructors</h2>
9191
<span class="name">{{{linkedName}}}</span><span class="signature">({{{ linkedParams }}})</span>
9292
</dt>
9393
<dd>
94-
{{{ oneLineDoc }}}
94+
{{{ oneLineDoc }}} {{{ extendedDocLink }}}
9595
{{#isConst}}
9696
<div class="constructor-modifier features">const</div>
9797
{{/isConst}}

‎lib/templates/mixin.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ <h2>Constructors</h2>
8888
<span class="name">{{{linkedName}}}</span><span class="signature">({{{ linkedParams }}})</span>
8989
</dt>
9090
<dd>
91-
{{{ oneLineDoc }}}
91+
{{{ oneLineDoc }}} {{{ extendedDocLink }}}
9292
{{#isConst}}
9393
<div class="constructor-modifier features">const</div>
9494
{{/isConst}}

‎test/model_test.dart

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,9 @@ import 'dart:io';
99
import 'package:dartdoc/dartdoc.dart';
1010
import 'package:dartdoc/src/model/model.dart';
1111
import 'package:dartdoc/src/render/category_renderer.dart';
12-
import 'package:dartdoc/src/render/parameter_renderer.dart';
1312
import 'package:dartdoc/src/render/enum_field_renderer.dart';
13+
import 'package:dartdoc/src/render/model_element_renderer.dart';
14+
import 'package:dartdoc/src/render/parameter_renderer.dart';
1415
import 'package:dartdoc/src/render/typedef_renderer.dart';
1516
import 'package:dartdoc/src/warnings.dart';
1617
import 'package:test/test.dart';
@@ -584,7 +585,7 @@ void main() {
584585
expect(
585586
fakeLibrary.oneLineDoc,
586587
equals(
587-
'WOW FAKE PACKAGE IS <strong>BEST</strong> <a href="http://example.org">PACKAGE</a> <a href="fake/fake-library.html">[...]</a>'));
588+
'WOW FAKE PACKAGE IS <strong>BEST</strong> <a href="http://example.org">PACKAGE</a>'));
588589
});
589590

590591
test('has properties', () {
@@ -1196,7 +1197,7 @@ void main() {
11961197
expect(
11971198
add.oneLineDoc,
11981199
equals(
1199-
'Adds <code>value</code> to the end of this list,\nextending the length by one. <a href="fake/SpecialList/add.html">[...]</a>'));
1200+
'Adds <code>value</code> to the end of this list,\nextending the length by one.'));
12001201
});
12011202

12021203
test(
@@ -1322,8 +1323,10 @@ void main() {
13221323
});
13231324

13241325
test('bullet points work in top level variables', () {
1325-
expect(bulletDoced.oneLineDoc,
1326-
contains('<a href="fake/bulletDoced-constant.html">[...]</a>'));
1326+
expect(
1327+
bulletDoced.extendedDocLink,
1328+
equals(
1329+
ModelElementRendererHtml().renderExtendedDocLink(bulletDoced)));
13271330
expect(bulletDoced.documentationAsHtml, contains('<li>'));
13281331
});
13291332
});
@@ -1999,6 +2002,7 @@ void main() {
19992002
expect(dog.isConst, isTrue);
20002003
expect(
20012004
dog.constantValue, equals(EnumFieldRendererHtml().renderValue(dog)));
2005+
expect(dog.extendedDocLink, equals(''));
20022006
});
20032007

20042008
test('constants have correct indicies', () {
@@ -2757,10 +2761,11 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
27572761

27582762
test('has extended documentation', () {
27592763
expect(lengthX.hasExtendedDocumentation, isTrue);
2760-
expect(
2761-
lengthX.oneLineDoc,
2762-
equals(
2763-
'Returns a length. <a href="fake/WithGetterAndSetter/lengthX.html">[...]</a>'));
2764+
expect(lengthX.oneLineDoc, equals('Returns a length.'));
2765+
// TODO(jdkoren): This is left here to have at least one literal matching
2766+
// test for extendedDocLink. Move this when extracting renderer tests.
2767+
expect(lengthX.extendedDocLink,
2768+
equals('<a href="fake/WithGetterAndSetter/lengthX.html">[...]</a>'));
27642769
expect(lengthX.documentation, contains('the fourth dimension'));
27652770
expect(lengthX.documentation, isNot(contains('[...]')));
27662771
});

‎testing/test_package_custom_templates/templates/class.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ <h2>Constructors</h2>
1818
{{{linkedName}}}({{{ linkedParams }}})
1919
</dt>
2020
<dd>
21-
{{{ oneLineDoc }}}
21+
{{{ oneLineDoc }}} {{{ extendedDocLink }}}
2222
</dd>
2323
{{/publicConstructors}}
2424
</dl>
@@ -30,7 +30,7 @@ <h2>Constructors</h2>
3030
<h2>Methods</h2>
3131
<dl>
3232
{{#allPublicInstanceMethods}}
33-
{{{ oneLineDoc }}}
33+
{{{ oneLineDoc }}} {{{ extendedDocLink }}}
3434
{{/allPublicInstanceMethods}}
3535
</dl>
3636
</section>

‎testing/test_package_custom_templates/templates/index.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ <h2>{{name}}</h2>
2020
{{/isFirstPackage}}
2121
<dl>
2222
{{#defaultCategory.publicLibraries}}
23-
{{{ oneLineDoc }}}
23+
{{{ oneLineDoc }}} {{{ extendedDocLink }}}
2424
{{/defaultCategory.publicLibraries}}
2525
{{#categoriesWithPublicLibraries}}
2626
<h3>{{name}}</h3>
@@ -29,7 +29,7 @@ <h3>{{name}}</h3>
2929
{{{ linkedName }}}
3030
</dt>
3131
<dd>
32-
{{#isDocumented}}{{{ oneLineDoc }}}{{/isDocumented}}
32+
{{#isDocumented}}{{{ oneLineDoc }}} {{{ extendedDocLink }}}{{/isDocumented}}
3333
</dd>
3434
{{/publicLibraries}}
3535
{{/categoriesWithPublicLibraries}}

‎testing/test_package_custom_templates/templates/library.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ <h2>Classes</h2>
1919
{{{linkedName}}}{{{linkedGenericParameters}}}
2020
</dt>
2121
<dd>
22-
{{{ oneLineDoc }}}
22+
{{{ oneLineDoc }}} {{{ extendedDocLink }}}
2323
</dd>
2424
{{/library.publicClasses}}
2525
</dl>
@@ -33,7 +33,7 @@ <h2>Functions</h2>
3333
<dl>
3434
{{#library.publicFunctions}}
3535
{{{linkedName}}}{{{linkedGenericParameters}}}
36-
{{{ oneLineDoc }}}
36+
{{{ oneLineDoc }}} {{{ extendedDocLink }}}
3737
{{/library.publicFunctions}}
3838
</dl>
3939
</div>

0 commit comments

Comments
 (0)