Add flag and rebuild test package docs (#1457)

* Add flag and rebuild test package docs

* review comments

Author: jcollins-g

bin/dartdoc.dart

@@ -158,6 +158,28 @@ main(List<String> arguments) async {
   DartSdk sdk = new FolderBasedDartSdk(PhysicalResourceProvider.INSTANCE,
       PhysicalResourceProvider.INSTANCE.getFolder(sdkDir.path));
 
+  List<String> dropTextFrom = [];
+  if (args['hide-sdk-text']) {
+    dropTextFrom.addAll([
+      'dart.async',
+      'dart.collection',
+      'dart.convert',
+      'dart.core',
+      'dart.developer',
+      'dart.html',
+      'dart.indexed_db',
+      'dart.io',
+      'dart.lisolate',
+      'dart.js',
+      'dart.js_util',
+      'dart.math',
+      'dart.mirrors',
+      'dart.svg',
+      'dart.typed_data',
+      'dart.web_audio'
+    ]);
+  }
+
   setConfig(
       addCrossdart: addCrossdart,
       examplePathPrefix: args['example-path-prefix'],
@@ -166,7 +188,8 @@ main(List<String> arguments) async {
       inputDir: inputDir,
       sdkVersion: sdk.sdkVersion,
       autoIncludeDependencies: args['auto-include-dependencies'],
-      categoryOrder: args['category-order']);
+      categoryOrder: args['category-order'],
+      dropTextFrom: dropTextFrom);
 
   DartDoc dartdoc = new DartDoc(inputDir, excludeLibraries, sdkDir, generators,
       outputDir, packageMeta, includeLibraries,
@@ -266,6 +289,15 @@ ArgParser _createArgsParser() {
           "Generates `index.json` with indentation and newlines. The file is larger, but it's also easier to diff.",
       negatable: false,
       defaultsTo: false);
+  parser.addFlag(
+    'hide-sdk-text',
+    help:
+        "Drop all text for SDK components.  Helpful for integration tests for dartdoc, probably not useful for anything else.",
+    negatable: true,
+    defaultsTo: false,
+    hide: true,
+  );
+
   return parser;
 }
 

lib/src/config.dart

@@ -16,6 +16,7 @@ class Config {
   final String sdkVersion;
   final bool autoIncludeDependencies;
   final List<String> categoryOrder;
+  final List<String> dropTextFrom;
   Config._(
       this.inputDir,
       this.showWarnings,
@@ -24,7 +25,8 @@ class Config {
       this.includeSource,
       this.sdkVersion,
       this.autoIncludeDependencies,
-      this.categoryOrder);
+      this.categoryOrder,
+      this.dropTextFrom);
 }
 
 Config _config;
@@ -38,10 +40,10 @@ void setConfig(
     bool includeSource: true,
     String sdkVersion,
     bool autoIncludeDependencies: false,
-    List<String> categoryOrder}) {
-  if (categoryOrder == null) {
-    categoryOrder = new UnmodifiableListView<String>([]);
-  }
+    List<String> categoryOrder,
+    List<String> dropTextFrom}) {
+  categoryOrder ??= new UnmodifiableListView<String>([]);
+  dropTextFrom ??= new UnmodifiableListView<String>([]);
   _config = new Config._(
       inputDir,
       showWarnings,
@@ -50,5 +52,6 @@ void setConfig(
       includeSource,
       sdkVersion,
       autoIncludeDependencies,
-      categoryOrder);
+      categoryOrder,
+      dropTextFrom);
 }

lib/src/markdown_processor.dart

@@ -6,7 +6,6 @@
 library dartdoc.markdown_processor;
 
 import 'dart:convert';
-import 'dart:io';
 import 'dart:math';
 
 import 'package:analyzer/dart/ast/ast.dart';

lib/src/model.dart

@@ -1956,11 +1956,15 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
 
   String get _documentationLocal {
     if (_rawDocs != null) return _rawDocs;
-    _rawDocs = _computeDocumentationComment ?? '';
-    _rawDocs = stripComments(_rawDocs) ?? '';
-    _rawDocs = _injectExamples(_rawDocs);
-    _rawDocs = _stripMacroTemplatesAndAddToIndex(_rawDocs);
-    _rawDocs = _injectMacros(_rawDocs);
+    if (config.dropTextFrom.contains(element.library.name)) {
+      _rawDocs = '';
+    } else {
+      _rawDocs = _computeDocumentationComment ?? '';
+      _rawDocs = stripComments(_rawDocs) ?? '';
+      _rawDocs = _injectExamples(_rawDocs);
+      _rawDocs = _stripMacroTemplatesAndAddToIndex(_rawDocs);
+      _rawDocs = _injectMacros(_rawDocs);
+    }
     return _rawDocs;
   }
 

test/compare_output_test.dart

@@ -54,6 +54,7 @@ void main() {
         '--auto-include-dependencies',
         '--example-path-prefix',
         'examples',
+        '--hide-sdk-text',
         '--exclude',
         'dart.async,dart.collection,dart.convert,dart.core,dart.math,dart.typed_data,meta',
         '--no-include-source',

test/dartdoc_test.dart

@@ -21,6 +21,7 @@ void main() {
 
     setUp(() {
       tempDir = Directory.systemTemp.createTempSync('dartdoc.test.');
+      setConfig();
     });
 
     tearDown(() {

testing/test_package_docs/ex/Animal-class.html

@@ -182,15 +182,15 @@ <h2>Properties</h2>
           <span class="signature">&#8594; int</span>
         </dt>
         <dd class="inherited">
-          The hash code for this object.
+          
           <div class="features">read-only, inherited</div>
 </dd>
         <dt id="runtimeType" class="property inherited">
           <span class="name"><a href="ex/Animal/runtimeType.html">runtimeType</a></span>
           <span class="signature">&#8594; Type</span>
         </dt>
         <dd class="inherited">
-          A representation of the runtime type of the object.
+          
           <div class="features">read-only, inherited</div>
 </dd>
       </dl>
@@ -205,7 +205,7 @@ <h2>Methods</h2>
           </span>
         </dt>
         <dd class="inherited">
-          Invoked when a non-existent method or property is accessed.
+          
           <div class="features">inherited</div>
 </dd>
         <dt id="toString" class="callable inherited">
@@ -214,7 +214,7 @@ <h2>Methods</h2>
           </span>
         </dt>
         <dd class="inherited">
-          Returns a string representation of this object.
+          
           <div class="features">inherited</div>
 </dd>
       </dl>
@@ -229,7 +229,7 @@ <h2>Operators</h2>
           </span>
         </dt>
         <dd class="inherited">
-          The equality operator.
+          
           <div class="features">inherited</div>
 </dd>
       </dl>

testing/test_package_docs/ex/Animal/hashCode.html

@@ -83,31 +83,7 @@ <h5>enum Animal</h5>
         <span class="returntype">int</span>
         <span class="name ">hashCode</span></section>
 
-      <section class="desc markdown">
-  <p>The hash code for this object.</p>
-<p>A hash code is a single integer which represents the state of the object
-that affects <code>==</code> comparisons.</p>
-<p>All objects have hash codes.
-The default hash code represents only the identity of the object,
-the same way as the default <code>==</code> implementation only considers objects
-equal if they are identical (see <code>identityHashCode</code>).</p>
-<p>If <code>==</code> is overridden to use the object state instead,
-the hash code must also be changed to represent that state.</p>
-<p>Hash codes must be the same for objects that are equal to each other
-according to <code>==</code>.
-The hash code of an object should only change if the object changes
-in a way that affects equality.
-There are no further requirements for the hash codes.
-They need not be consistent between executions of the same program
-and there are no distribution guarantees.</p>
-<p>Objects that are not equal are allowed to have the same hash code,
-it is even technically allowed that all instances have the same hash code,
-but if clashes happen too often, it may reduce the efficiency of hash-based
-data structures like <code>HashSet</code> or <code>HashMap</code>.</p>
-<p>If a subclass overrides <code>hashCode</code>, it should override the
-<code>==</code> operator as well to maintain consistency.</p>
-</section>
-</section>
+      </section>
 
 
 

testing/test_package_docs/ex/Animal/noSuchMethod.html

@@ -79,12 +79,6 @@ <h5>enum Animal</h5>
       <span class="returntype">dynamic</span>
       <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>)
     </section>
-    <section class="desc markdown">
-      <p>Invoked when a non-existent method or property is accessed.</p>
-<p>Classes can override <code>noSuchMethod</code> to provide custom behavior.</p>
-<p>If a value is returned, it becomes the result of the original invocation.</p>
-<p>The default behavior is to throw a <code>NoSuchMethodError</code>.</p>
-    </section>
 
 
 

testing/test_package_docs/ex/Animal/operator_equals.html

@@ -79,26 +79,6 @@ <h5>enum Animal</h5>
       <span class="returntype">bool</span>
       <span class="name ">operator ==</span>(<wbr><span class="parameter" id="==-param-other"><span class="parameter-name">other</span></span>)
     </section>
-    <section class="desc markdown">
-      <p>The equality operator.</p>
-<p>The default behavior for all <code>Object</code>s is to return true if and
-only if <code>this</code> and <code>other</code> are the same object.</p>
-<p>Override this method to specify a different equality relation on
-a class. The overriding method must still be an equivalence relation.
-That is, it must be:</p><ul><li>
-<p>Total: It must return a boolean for all arguments. It should never throw
-or return <code>null</code>.</p></li><li>
-<p>Reflexive: For all objects <code>o</code>, <code>o == o</code> must be true.</p></li><li>
-<p>Symmetric: For all objects <code>o1</code> and <code>o2</code>, <code>o1 == o2</code> and <code>o2 == o1</code> must
-either both be true, or both be false.</p></li><li>
-<p>Transitive: For all objects <code>o1</code>, <code>o2</code>, and <code>o3</code>, if <code>o1 == o2</code> and
-<code>o2 == o3</code> are true, then <code>o1 == o3</code> must be true.</p></li></ul>
-<p>The method should also be consistent over time,
-so whether two objects are equal should only change
-if at least one of the objects was modified.</p>
-<p>If a subclass overrides the equality operator it should override
-the <code>hashCode</code> method as well to maintain consistency.</p>
-    </section>