Skip to content

Commit e58142a

Browse files
authored
Add links for more details in API docs. (#1461)
* add ellipses with link to detailed docs * Patch up tests * dartfmt
1 parent 462dde8 commit e58142a

17 files changed

+41
-31
lines changed

lib/src/model.dart

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2289,6 +2289,15 @@ abstract class ModelElement extends Nameable
22892289
return "(${p.toUri(sourceFileName)})";
22902290
}
22912291

2292+
/// Returns a link to extended documentation, or the empty string if that
2293+
/// does not exist.
2294+
String get extendedDocLink {
2295+
if (hasExtendedDocumentation) {
2296+
return '<a href="${href}">[...]</a>';
2297+
}
2298+
return '';
2299+
}
2300+
22922301
/// Returns the fully qualified name.
22932302
///
22942303
/// For example: libraryName.className.methodName
@@ -2415,7 +2424,8 @@ abstract class ModelElement extends Nameable
24152424
String get genericParameters => '';
24162425

24172426
@override
2418-
String get oneLineDoc => _documentation.asOneLiner;
2427+
String get oneLineDoc =>
2428+
'${_documentation.asOneLiner}${extendedDocLink.isEmpty ? "" : " $extendedDocLink"}';
24192429

24202430
ModelElement get overriddenElement => null;
24212431

test/model_test.dart

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -207,7 +207,7 @@ void main() {
207207
expect(
208208
fakeLibrary.oneLineDoc,
209209
equals(
210-
'WOW FAKE PACKAGE IS <strong>BEST</strong> <a href="http://example.org">PACKAGE</a>'));
210+
'WOW FAKE PACKAGE IS <strong>BEST</strong> <a href="http://example.org">PACKAGE</a> <a href="fake/fake-library.html">[...]</a>'));
211211
});
212212

213213
test('has properties', () {
@@ -504,7 +504,7 @@ void main() {
504504
expect(
505505
add.oneLineDoc,
506506
equals(
507-
'Adds <code>value</code> to the end of this list,\nextending the length by one.'));
507+
'Adds <code>value</code> to the end of this list,\nextending the length by one. <a href="fake/SpecialList/add.html">[...]</a>'));
508508
});
509509

510510
test(

testing/test_package_docs/ex/Apple-class.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,7 @@ <h2>Properties</h2>
166166
</span>
167167
</dt>
168168
<dd>
169-
The getter for <code>s</code>
169+
The getter for <code>s</code> <a href="ex/Apple/s.html">[...]</a>
170170
<div class="features">read / write</div>
171171
</dd>
172172
<dt id="hashCode" class="property inherited">
@@ -206,7 +206,7 @@ <h2>Methods</h2>
206206
</span>
207207
</dt>
208208
<dd>
209-
This is a method.
209+
This is a method. <a href="ex/Apple/m1.html">[...]</a>
210210

211211
</dd>
212212
<dt id="methodWithTypedefParam" class="callable">

testing/test_package_docs/ex/B-class.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -240,7 +240,7 @@ <h2>Methods</h2>
240240
</span>
241241
</dt>
242242
<dd>
243-
This is a method.
243+
This is a method. <a href="ex/B/m1.html">[...]</a>
244244

245245
</dd>
246246
<dt id="writeMsg" class="callable">

testing/test_package_docs/ex/Dog-class.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -313,7 +313,7 @@ <h2>Methods</h2>
313313
</span>
314314
</dt>
315315
<dd>
316-
Macro method
316+
Macro method <a href="ex/Dog/withMacro.html">[...]</a>
317317

318318
</dd>
319319
<dt id="withMacro2" class="callable">

testing/test_package_docs/ex/F-class.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -327,7 +327,7 @@ <h2>Methods</h2>
327327
</span>
328328
</dt>
329329
<dd class="inherited">
330-
Macro method
330+
Macro method <a href="ex/Dog/withMacro.html">[...]</a>
331331
<div class="features">inherited</div>
332332
</dd>
333333
<dt id="withMacro2" class="callable inherited">

testing/test_package_docs/ex/ex-library.html

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ <h2>Classes</h2>
6767
<span class="name "><a href="ex/Apple-class.html">Apple</a></span>
6868
</dt>
6969
<dd>
70-
Sample class <code>String</code>
70+
Sample class <code>String</code> <a href="ex/Apple-class.html">[...]</a>
7171
</dd>
7272
<dt id="aThingToDo">
7373
<span class="name "><a href="ex/aThingToDo-class.html">aThingToDo</a></span>
@@ -79,7 +79,7 @@ <h2>Classes</h2>
7979
<span class="name "><a href="ex/B-class.html">B</a></span>
8080
</dt>
8181
<dd>
82-
Extends class <a href="ex/Apple-class.html">Apple</a>, use <a href="ex/Apple/Apple.html">new Apple</a> or <a href="ex/Apple/Apple.fromString.html">new Apple.fromString</a>
82+
Extends class <a href="ex/Apple-class.html">Apple</a>, use <a href="ex/Apple/Apple.html">new Apple</a> or <a href="ex/Apple/Apple.fromString.html">new Apple.fromString</a> <a href="ex/B-class.html">[...]</a>
8383
</dd>
8484
<dt id="Cat">
8585
<span class="name "><a href="ex/Cat-class.html">Cat</a></span>
@@ -115,7 +115,7 @@ <h2>Classes</h2>
115115
<span class="name "><a href="ex/Dog-class.html">Dog</a></span>
116116
</dt>
117117
<dd>
118-
implements <a href="ex/Cat-class.html">Cat</a>, <a href="ex/E-class.html">E</a>
118+
implements <a href="ex/Cat-class.html">Cat</a>, <a href="ex/E-class.html">E</a> <a href="ex/Dog-class.html">[...]</a>
119119
</dd>
120120
<dt id="E">
121121
<span class="name "><a href="ex/E-class.html">E</a></span>
@@ -171,7 +171,7 @@ <h2>Classes</h2>
171171
<span class="name "><a href="ex/ShapeType-class.html">ShapeType</a></span>
172172
</dt>
173173
<dd>
174-
Foo bar.
174+
Foo bar. <a href="ex/ShapeType-class.html">[...]</a>
175175
</dd>
176176
<dt id="SpecializedDuration">
177177
<span class="name "><a href="ex/SpecializedDuration-class.html">SpecializedDuration</a></span>

testing/test_package_docs/fake/BaseForDocComments-class.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -186,7 +186,7 @@ <h2>Methods</h2>
186186
</span>
187187
</dt>
188188
<dd>
189-
Takes a <code>value</code> and returns a String.
189+
Takes a <code>value</code> and returns a String. <a href="fake/BaseForDocComments/doAwesomeStuff.html">[...]</a>
190190

191191
</dd>
192192
<dt id="noSuchMethod" class="callable inherited">

testing/test_package_docs/fake/LongFirstLine-class.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,7 @@ <h2>Constructors</h2>
174174
<span class="name"><a href="fake/LongFirstLine/LongFirstLine.fromMap.html">LongFirstLine.fromMap</a></span><span class="signature">(<span class="parameter" id="fromMap-param-data"><span class="type-annotation">Map</span> <span class="parameter-name">data</span></span>)</span>
175175
</dt>
176176
<dd>
177-
Named constructors are awesome.
177+
Named constructors are awesome. <a href="fake/LongFirstLine/LongFirstLine.fromMap.html">[...]</a>
178178
</dd>
179179
</dl>
180180
</section>
@@ -282,7 +282,7 @@ <h2>Methods</h2>
282282
</span>
283283
</dt>
284284
<dd class="inherited">
285-
In the super class.
285+
In the super class. <a href="fake/SuperAwesomeClass/fly.html">[...]</a>
286286
<div class="features">inherited</div>
287287
</dd>
288288
<dt id="noSuchMethod" class="callable inherited">
@@ -390,7 +390,7 @@ <h2>Static Methods</h2>
390390
</span>
391391
</dt>
392392
<dd>
393-
Just a static method with no parameters.
393+
Just a static method with no parameters. <a href="fake/LongFirstLine/staticMethodNoParams.html">[...]</a>
394394

395395
</dd>
396396
<dt id="staticMethodReturnsVoid" class="callable">

testing/test_package_docs/fake/SubForDocComments-class.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -200,7 +200,7 @@ <h2>Methods</h2>
200200
</span>
201201
</dt>
202202
<dd class="inherited">
203-
Takes a <code>value</code> and returns a String.
203+
Takes a <code>value</code> and returns a String. <a href="fake/BaseForDocComments/doAwesomeStuff.html">[...]</a>
204204
<div class="features">inherited</div>
205205
</dd>
206206
<dt id="noSuchMethod" class="callable inherited">

testing/test_package_docs/fake/SuperAwesomeClass-class.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -193,7 +193,7 @@ <h2>Methods</h2>
193193
</span>
194194
</dt>
195195
<dd>
196-
In the super class.
196+
In the super class. <a href="fake/SuperAwesomeClass/fly.html">[...]</a>
197197

198198
</dd>
199199
<dt id="noSuchMethod" class="callable inherited">

testing/test_package_docs/fake/WithGetterAndSetter-class.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -158,7 +158,7 @@ <h2>Properties</h2>
158158
</span>
159159
</dt>
160160
<dd>
161-
Returns a length.
161+
Returns a length. <a href="fake/WithGetterAndSetter/lengthX.html">[...]</a>
162162
<div class="features">read / write</div>
163163
</dd>
164164
<dt id="hashCode" class="property inherited">

testing/test_package_docs/fake/fake-library.html

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ <h2>Classes</h2>
110110
<span class="name "><a href="fake/ConstantClass-class.html">ConstantClass</a></span>
111111
</dt>
112112
<dd>
113-
For make-better testing of constants.
113+
For make-better testing of constants. <a href="fake/ConstantClass-class.html">[...]</a>
114114
</dd>
115115
<dt id="Cool">
116116
<span class="name "><a href="fake/Cool-class.html">Cool</a></span>
@@ -160,7 +160,7 @@ <h2>Classes</h2>
160160
</dt>
161161
<dd>
162162
This is a very long line spread
163-
across... wait for it... two physical lines.
163+
across... wait for it... two physical lines. <a href="fake/LongFirstLine-class.html">[...]</a>
164164
</dd>
165165
<dt id="MixMeIn">
166166
<span class="name "><a href="fake/MixMeIn-class.html">MixMeIn</a></span>
@@ -326,7 +326,7 @@ <h2>Constants</h2>
326326
<span class="signature">&#8594; String</span>
327327
</dt>
328328
<dd>
329-
Up is a direction.
329+
Up is a direction. <a href="fake/UP-constant.html">[...]</a>
330330

331331
<div>
332332
<span class="signature"><code>&#39;up&#39;</code></span>
@@ -399,7 +399,7 @@ <h2>Properties</h2>
399399
</span>
400400
</dt>
401401
<dd>
402-
The getter for setAndGet.
402+
The getter for setAndGet. <a href="fake/setAndGet.html">[...]</a>
403403
<div class="features">read / write</div>
404404
</dd>
405405
<dt id="simpleProperty" class="property">
@@ -442,7 +442,7 @@ <h2>Functions</h2>
442442
</span>
443443
</dt>
444444
<dd>
445-
This function has two parameters that are functions.
445+
This function has two parameters that are functions. <a href="fake/functionWithFunctionParameters.html">[...]</a>
446446

447447
</dd>
448448
<dt id="myGenericFunction" class="callable">
@@ -496,7 +496,7 @@ <h2>Functions</h2>
496496
</span>
497497
</dt>
498498
<dd>
499-
Testing <a href="fake/NAME_WITH_TWO_UNDERSCORES-constant.html">NAME_WITH_TWO_UNDERSCORES</a> should not be italicized.
499+
Testing <a href="fake/NAME_WITH_TWO_UNDERSCORES-constant.html">NAME_WITH_TWO_UNDERSCORES</a> should not be italicized. <a href="fake/short.html">[...]</a>
500500

501501
</dd>
502502
<dt id="soIntense" class="callable">
@@ -533,7 +533,7 @@ <h2>Functions</h2>
533533
</span>
534534
</dt>
535535
<dd>
536-
Top-level function 3 params and 1 optional positional param.
536+
Top-level function 3 params and 1 optional positional param. <a href="fake/topLevelFunction.html">[...]</a>
537537

538538
</dd>
539539
</dl>

testing/test_package_docs/index.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ <h2>Libraries</h2>
9393
<code class="language-dart">void main() {
9494
// in Dart!
9595
}
96-
</code>
96+
</code> <a href="code_in_comments/code_in_comments-library.html">[...]</a>
9797
</dd>
9898
<dt id="css">
9999
<span class="name"><a href="css/css-library.html">css</a></span>
@@ -112,7 +112,7 @@ <h2>Libraries</h2>
112112
<span class="name"><a href="fake/fake-library.html">fake</a></span>
113113
</dt>
114114
<dd>
115-
WOW FAKE PACKAGE IS <strong>BEST</strong> <a href="http://example.org">PACKAGE</a>
115+
WOW FAKE PACKAGE IS <strong>BEST</strong> <a href="http://example.org">PACKAGE</a> <a href="fake/fake-library.html">[...]</a>
116116
</dd>
117117
<dt id="is_deprecated">
118118
<span class="name"><a class="deprecated" href="is_deprecated/is_deprecated-library.html">is_deprecated</a></span>

testing/test_package_docs/two_exports/BaseClass-class.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ <h2>Properties</h2>
105105
</span>
106106
</dt>
107107
<dd class="inherited">
108-
Returns a length.
108+
Returns a length. <a href="fake/WithGetterAndSetter/lengthX.html">[...]</a>
109109
<div class="features">read / write, inherited</div>
110110
</dd>
111111
<dt id="runtimeType" class="property inherited">

testing/test_package_docs/two_exports/ExtendingClass-class.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ <h2>Properties</h2>
107107
</span>
108108
</dt>
109109
<dd class="inherited">
110-
Returns a length.
110+
Returns a length. <a href="fake/WithGetterAndSetter/lengthX.html">[...]</a>
111111
<div class="features">read / write, inherited</div>
112112
</dd>
113113
<dt id="runtimeType" class="property inherited">

testing/test_package_docs/two_exports/two_exports-library.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ <h2>Classes</h2>
7070
<span class="name "><a href="two_exports/ExtendingClass-class.html">ExtendingClass</a></span>
7171
</dt>
7272
<dd>
73-
Extending class extends <a href="two_exports/BaseClass-class.html">BaseClass</a>.
73+
Extending class extends <a href="two_exports/BaseClass-class.html">BaseClass</a>. <a href="two_exports/ExtendingClass-class.html">[...]</a>
7474
</dd>
7575
</dl>
7676
</section>

0 commit comments

Comments
 (0)