Skip to content

Commit 80b2a60

Browse files
jcollins-gjcollins-g
authored
Add flag and rebuild test package docs (#1457)
* Add flag and rebuild test package docs * review comments
1 parent 106721c commit 80b2a60

File tree

352 files changed

+529
-3549
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

352 files changed

+529
-3549
lines changed

‎bin/dartdoc.dart

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,28 @@ main(List<String> arguments) async {
158158
DartSdk sdk = new FolderBasedDartSdk(PhysicalResourceProvider.INSTANCE,
159159
PhysicalResourceProvider.INSTANCE.getFolder(sdkDir.path));
160160

161+
List<String> dropTextFrom = [];
162+
if (args['hide-sdk-text']) {
163+
dropTextFrom.addAll([
164+
'dart.async',
165+
'dart.collection',
166+
'dart.convert',
167+
'dart.core',
168+
'dart.developer',
169+
'dart.html',
170+
'dart.indexed_db',
171+
'dart.io',
172+
'dart.lisolate',
173+
'dart.js',
174+
'dart.js_util',
175+
'dart.math',
176+
'dart.mirrors',
177+
'dart.svg',
178+
'dart.typed_data',
179+
'dart.web_audio'
180+
]);
181+
}
182+
161183
setConfig(
162184
addCrossdart: addCrossdart,
163185
examplePathPrefix: args['example-path-prefix'],
@@ -166,7 +188,8 @@ main(List<String> arguments) async {
166188
inputDir: inputDir,
167189
sdkVersion: sdk.sdkVersion,
168190
autoIncludeDependencies: args['auto-include-dependencies'],
169-
categoryOrder: args['category-order']);
191+
categoryOrder: args['category-order'],
192+
dropTextFrom: dropTextFrom);
170193

171194
DartDoc dartdoc = new DartDoc(inputDir, excludeLibraries, sdkDir, generators,
172195
outputDir, packageMeta, includeLibraries,
@@ -266,6 +289,15 @@ ArgParser _createArgsParser() {
266289
"Generates `index.json` with indentation and newlines. The file is larger, but it's also easier to diff.",
267290
negatable: false,
268291
defaultsTo: false);
292+
parser.addFlag(
293+
'hide-sdk-text',
294+
help:
295+
"Drop all text for SDK components. Helpful for integration tests for dartdoc, probably not useful for anything else.",
296+
negatable: true,
297+
defaultsTo: false,
298+
hide: true,
299+
);
300+
269301
return parser;
270302
}
271303

‎lib/src/config.dart

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ class Config {
1616
final String sdkVersion;
1717
final bool autoIncludeDependencies;
1818
final List<String> categoryOrder;
19+
final List<String> dropTextFrom;
1920
Config._(
2021
this.inputDir,
2122
this.showWarnings,
@@ -24,7 +25,8 @@ class Config {
2425
this.includeSource,
2526
this.sdkVersion,
2627
this.autoIncludeDependencies,
27-
this.categoryOrder);
28+
this.categoryOrder,
29+
this.dropTextFrom);
2830
}
2931

3032
Config _config;
@@ -38,10 +40,10 @@ void setConfig(
3840
bool includeSource: true,
3941
String sdkVersion,
4042
bool autoIncludeDependencies: false,
41-
List<String> categoryOrder}) {
42-
if (categoryOrder == null) {
43-
categoryOrder = new UnmodifiableListView<String>([]);
44-
}
43+
List<String> categoryOrder,
44+
List<String> dropTextFrom}) {
45+
categoryOrder ??= new UnmodifiableListView<String>([]);
46+
dropTextFrom ??= new UnmodifiableListView<String>([]);
4547
_config = new Config._(
4648
inputDir,
4749
showWarnings,
@@ -50,5 +52,6 @@ void setConfig(
5052
includeSource,
5153
sdkVersion,
5254
autoIncludeDependencies,
53-
categoryOrder);
55+
categoryOrder,
56+
dropTextFrom);
5457
}

‎lib/src/markdown_processor.dart

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@
66
library dartdoc.markdown_processor;
77

88
import 'dart:convert';
9-
import 'dart:io';
109
import 'dart:math';
1110

1211
import 'package:analyzer/dart/ast/ast.dart';

‎lib/src/model.dart

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1956,11 +1956,15 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
19561956

19571957
String get _documentationLocal {
19581958
if (_rawDocs != null) return _rawDocs;
1959-
_rawDocs = _computeDocumentationComment ?? '';
1960-
_rawDocs = stripComments(_rawDocs) ?? '';
1961-
_rawDocs = _injectExamples(_rawDocs);
1962-
_rawDocs = _stripMacroTemplatesAndAddToIndex(_rawDocs);
1963-
_rawDocs = _injectMacros(_rawDocs);
1959+
if (config.dropTextFrom.contains(element.library.name)) {
1960+
_rawDocs = '';
1961+
} else {
1962+
_rawDocs = _computeDocumentationComment ?? '';
1963+
_rawDocs = stripComments(_rawDocs) ?? '';
1964+
_rawDocs = _injectExamples(_rawDocs);
1965+
_rawDocs = _stripMacroTemplatesAndAddToIndex(_rawDocs);
1966+
_rawDocs = _injectMacros(_rawDocs);
1967+
}
19641968
return _rawDocs;
19651969
}
19661970

‎test/compare_output_test.dart

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ void main() {
5454
'--auto-include-dependencies',
5555
'--example-path-prefix',
5656
'examples',
57+
'--hide-sdk-text',
5758
'--exclude',
5859
'dart.async,dart.collection,dart.convert,dart.core,dart.math,dart.typed_data,meta',
5960
'--no-include-source',

‎test/dartdoc_test.dart

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ void main() {
2121

2222
setUp(() {
2323
tempDir = Directory.systemTemp.createTempSync('dartdoc.test.');
24+
setConfig();
2425
});
2526

2627
tearDown(() {

‎testing/test_package_docs/ex/Animal-class.html

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -182,15 +182,15 @@ <h2>Properties</h2>
182182
<span class="signature">&#8594; int</span>
183183
</dt>
184184
<dd class="inherited">
185-
The hash code for this object.
185+
186186
<div class="features">read-only, inherited</div>
187187
</dd>
188188
<dt id="runtimeType" class="property inherited">
189189
<span class="name"><a href="ex/Animal/runtimeType.html">runtimeType</a></span>
190190
<span class="signature">&#8594; Type</span>
191191
</dt>
192192
<dd class="inherited">
193-
A representation of the runtime type of the object.
193+
194194
<div class="features">read-only, inherited</div>
195195
</dd>
196196
</dl>
@@ -205,7 +205,7 @@ <h2>Methods</h2>
205205
</span>
206206
</dt>
207207
<dd class="inherited">
208-
Invoked when a non-existent method or property is accessed.
208+
209209
<div class="features">inherited</div>
210210
</dd>
211211
<dt id="toString" class="callable inherited">
@@ -214,7 +214,7 @@ <h2>Methods</h2>
214214
</span>
215215
</dt>
216216
<dd class="inherited">
217-
Returns a string representation of this object.
217+
218218
<div class="features">inherited</div>
219219
</dd>
220220
</dl>
@@ -229,7 +229,7 @@ <h2>Operators</h2>
229229
</span>
230230
</dt>
231231
<dd class="inherited">
232-
The equality operator.
232+
233233
<div class="features">inherited</div>
234234
</dd>
235235
</dl>

‎testing/test_package_docs/ex/Animal/hashCode.html

Lines changed: 1 addition & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -83,31 +83,7 @@ <h5>enum Animal</h5>
8383
<span class="returntype">int</span>
8484
<span class="name ">hashCode</span></section>
8585

86-
<section class="desc markdown">
87-
<p>The hash code for this object.</p>
88-
<p>A hash code is a single integer which represents the state of the object
89-
that affects <code>==</code> comparisons.</p>
90-
<p>All objects have hash codes.
91-
The default hash code represents only the identity of the object,
92-
the same way as the default <code>==</code> implementation only considers objects
93-
equal if they are identical (see <code>identityHashCode</code>).</p>
94-
<p>If <code>==</code> is overridden to use the object state instead,
95-
the hash code must also be changed to represent that state.</p>
96-
<p>Hash codes must be the same for objects that are equal to each other
97-
according to <code>==</code>.
98-
The hash code of an object should only change if the object changes
99-
in a way that affects equality.
100-
There are no further requirements for the hash codes.
101-
They need not be consistent between executions of the same program
102-
and there are no distribution guarantees.</p>
103-
<p>Objects that are not equal are allowed to have the same hash code,
104-
it is even technically allowed that all instances have the same hash code,
105-
but if clashes happen too often, it may reduce the efficiency of hash-based
106-
data structures like <code>HashSet</code> or <code>HashMap</code>.</p>
107-
<p>If a subclass overrides <code>hashCode</code>, it should override the
108-
<code>==</code> operator as well to maintain consistency.</p>
109-
</section>
110-
</section>
86+
</section>
11187

11288

11389

‎testing/test_package_docs/ex/Animal/noSuchMethod.html

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -79,12 +79,6 @@ <h5>enum Animal</h5>
7979
<span class="returntype">dynamic</span>
8080
<span class="name ">noSuchMethod</span>(<wbr><span class="parameter" id="noSuchMethod-param-invocation"><span class="type-annotation">Invocation</span> <span class="parameter-name">invocation</span></span>)
8181
</section>
82-
<section class="desc markdown">
83-
<p>Invoked when a non-existent method or property is accessed.</p>
84-
<p>Classes can override <code>noSuchMethod</code> to provide custom behavior.</p>
85-
<p>If a value is returned, it becomes the result of the original invocation.</p>
86-
<p>The default behavior is to throw a <code>NoSuchMethodError</code>.</p>
87-
</section>
8882

8983

9084

‎testing/test_package_docs/ex/Animal/operator_equals.html

Lines changed: 0 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -79,26 +79,6 @@ <h5>enum Animal</h5>
7979
<span class="returntype">bool</span>
8080
<span class="name ">operator ==</span>(<wbr><span class="parameter" id="==-param-other"><span class="parameter-name">other</span></span>)
8181
</section>
82-
<section class="desc markdown">
83-
<p>The equality operator.</p>
84-
<p>The default behavior for all <code>Object</code>s is to return true if and
85-
only if <code>this</code> and <code>other</code> are the same object.</p>
86-
<p>Override this method to specify a different equality relation on
87-
a class. The overriding method must still be an equivalence relation.
88-
That is, it must be:</p><ul><li>
89-
<p>Total: It must return a boolean for all arguments. It should never throw
90-
or return <code>null</code>.</p></li><li>
91-
<p>Reflexive: For all objects <code>o</code>, <code>o == o</code> must be true.</p></li><li>
92-
<p>Symmetric: For all objects <code>o1</code> and <code>o2</code>, <code>o1 == o2</code> and <code>o2 == o1</code> must
93-
either both be true, or both be false.</p></li><li>
94-
<p>Transitive: For all objects <code>o1</code>, <code>o2</code>, and <code>o3</code>, if <code>o1 == o2</code> and
95-
<code>o2 == o3</code> are true, then <code>o1 == o3</code> must be true.</p></li></ul>
96-
<p>The method should also be consistent over time,
97-
so whether two objects are equal should only change
98-
if at least one of the objects was modified.</p>
99-
<p>If a subclass overrides the equality operator it should override
100-
the <code>hashCode</code> method as well to maintain consistency.</p>
101-
</section>
10282

10383

10484

‎testing/test_package_docs/ex/Animal/runtimeType.html

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -83,10 +83,7 @@ <h5>enum Animal</h5>
8383
<span class="returntype">Type</span>
8484
<span class="name ">runtimeType</span></section>
8585

86-
<section class="desc markdown">
87-
<p>A representation of the runtime type of the object.</p>
88-
</section>
89-
</section>
86+
</section>
9087

9188

9289

‎testing/test_package_docs/ex/Animal/toString.html

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -79,9 +79,6 @@ <h5>enum Animal</h5>
7979
<span class="returntype">String</span>
8080
<span class="name ">toString</span>(<wbr>)
8181
</section>
82-
<section class="desc markdown">
83-
<p>Returns a string representation of this object.</p>
84-
</section>
8582

8683

8784

‎testing/test_package_docs/ex/Apple-class.html

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -184,15 +184,15 @@ <h2>Properties</h2>
184184
<span class="signature">&#8594; int</span>
185185
</dt>
186186
<dd class="inherited">
187-
The hash code for this object.
187+
188188
<div class="features">read-only, inherited</div>
189189
</dd>
190190
<dt id="runtimeType" class="property inherited">
191191
<span class="name"><a href="ex/Apple/runtimeType.html">runtimeType</a></span>
192192
<span class="signature">&#8594; Type</span>
193193
</dt>
194194
<dd class="inherited">
195-
A representation of the runtime type of the object.
195+
196196
<div class="features">read-only, inherited</div>
197197
</dd>
198198
</dl>
@@ -261,7 +261,7 @@ <h2>Methods</h2>
261261
</span>
262262
</dt>
263263
<dd class="inherited">
264-
Invoked when a non-existent method or property is accessed.
264+
265265
<div class="features">inherited</div>
266266
</dd>
267267
<dt id="toString" class="callable inherited">
@@ -270,7 +270,7 @@ <h2>Methods</h2>
270270
</span>
271271
</dt>
272272
<dd class="inherited">
273-
Returns a string representation of this object.
273+
274274
<div class="features">inherited</div>
275275
</dd>
276276
</dl>
@@ -294,7 +294,7 @@ <h2>Operators</h2>
294294
</span>
295295
</dt>
296296
<dd class="inherited">
297-
The equality operator.
297+
298298
<div class="features">inherited</div>
299299
</dd>
300300
</dl>

‎testing/test_package_docs/ex/Apple/hashCode.html

Lines changed: 1 addition & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -94,31 +94,7 @@ <h5>class Apple</h5>
9494
<span class="returntype">int</span>
9595
<span class="name ">hashCode</span></section>
9696

97-
<section class="desc markdown">
98-
<p>The hash code for this object.</p>
99-
<p>A hash code is a single integer which represents the state of the object
100-
that affects <code>==</code> comparisons.</p>
101-
<p>All objects have hash codes.
102-
The default hash code represents only the identity of the object,
103-
the same way as the default <code>==</code> implementation only considers objects
104-
equal if they are identical (see <code>identityHashCode</code>).</p>
105-
<p>If <code>==</code> is overridden to use the object state instead,
106-
the hash code must also be changed to represent that state.</p>
107-
<p>Hash codes must be the same for objects that are equal to each other
108-
according to <code>==</code>.
109-
The hash code of an object should only change if the object changes
110-
in a way that affects equality.
111-
There are no further requirements for the hash codes.
112-
They need not be consistent between executions of the same program
113-
and there are no distribution guarantees.</p>
114-
<p>Objects that are not equal are allowed to have the same hash code,
115-
it is even technically allowed that all instances have the same hash code,
116-
but if clashes happen too often, it may reduce the efficiency of hash-based
117-
data structures like <code>HashSet</code> or <code>HashMap</code>.</p>
118-
<p>If a subclass overrides <code>hashCode</code>, it should override the
119-
<code>==</code> operator as well to maintain consistency.</p>
120-
</section>
121-
</section>
97+
</section>
12298

12399

124100

‎testing/test_package_docs/ex/Apple/noSuchMethod.html

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -90,12 +90,6 @@ <h5>class Apple</h5>
9090
<span class="returntype">dynamic</span>
9191
<span class="name ">noSuchMethod</span>(<wbr><span class="parameter" id="noSuchMethod-param-invocation"><span class="type-annotation">Invocation</span> <span class="parameter-name">invocation</span></span>)
9292
</section>
93-
<section class="desc markdown">
94-
<p>Invoked when a non-existent method or property is accessed.</p>
95-
<p>Classes can override <code>noSuchMethod</code> to provide custom behavior.</p>
96-
<p>If a value is returned, it becomes the result of the original invocation.</p>
97-
<p>The default behavior is to throw a <code>NoSuchMethodError</code>.</p>
98-
</section>
9993

10094

10195

‎testing/test_package_docs/ex/Apple/operator_equals.html

Lines changed: 0 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -90,26 +90,6 @@ <h5>class Apple</h5>
9090
<span class="returntype">bool</span>
9191
<span class="name ">operator ==</span>(<wbr><span class="parameter" id="==-param-other"><span class="parameter-name">other</span></span>)
9292
</section>
93-
<section class="desc markdown">
94-
<p>The equality operator.</p>
95-
<p>The default behavior for all <code>Object</code>s is to return true if and
96-
only if <code>this</code> and <code>other</code> are the same object.</p>
97-
<p>Override this method to specify a different equality relation on
98-
a class. The overriding method must still be an equivalence relation.
99-
That is, it must be:</p><ul><li>
100-
<p>Total: It must return a boolean for all arguments. It should never throw
101-
or return <code>null</code>.</p></li><li>
102-
<p>Reflexive: For all objects <code>o</code>, <code>o == o</code> must be true.</p></li><li>
103-
<p>Symmetric: For all objects <code>o1</code> and <code>o2</code>, <code>o1 == o2</code> and <code>o2 == o1</code> must
104-
either both be true, or both be false.</p></li><li>
105-
<p>Transitive: For all objects <code>o1</code>, <code>o2</code>, and <code>o3</code>, if <code>o1 == o2</code> and
106-
<code>o2 == o3</code> are true, then <code>o1 == o3</code> must be true.</p></li></ul>
107-
<p>The method should also be consistent over time,
108-
so whether two objects are equal should only change
109-
if at least one of the objects was modified.</p>
110-
<p>If a subclass overrides the equality operator it should override
111-
the <code>hashCode</code> method as well to maintain consistency.</p>
112-
</section>
11393

11494

11595

0 commit comments

Comments
 (0)