Add --auto-include-dependencies [#1159] (#1327)

If `--auto-include-dependencies` flag is provided, dartdoc tries to
automatically add all the used libraries, even from other packages, to
the list of the documented libraries.

For that, it goes through each model element in a package, and finds
"used" elements for each element (e.g. from the parameters and from the
return type), and if any of these are from undocumented lib - it adds
that lib, and then rebuild `Package` with the new list of libs.

Testing: Flutter now generates docs for `vector_math_64` when
`--auto-include-dependencies` are provided. And the test package
adds library from `test_package_imported` because it uses it and has one
of the members of that lib in one of the Apple method's parameters.

Fixes #1159

Author: astashov

README.md

@@ -114,6 +114,11 @@ and then you can insert it via `{@macro template_name}`, like
 /// More comments
 ```
 
+### Auto including dependencies
+
+If `--auto-include-dependencies` flag is provided, dartdoc tries to automatically add
+all the used libraries, even from other packages, to the list of the documented libraries.
+
 ## Issues and bugs
 
 Please file reports on the [GitHub Issue Tracker][].

bin/dartdoc.dart

@@ -143,7 +143,8 @@ main(List<String> arguments) async {
       showWarnings: args['show-warnings'],
       includeSource: includeSource,
       inputDir: inputDir,
-      sdkVersion: sdk.sdkVersion);
+      sdkVersion: sdk.sdkVersion,
+      autoIncludeDependencies: args['auto-include-dependencies']);
 
   var dartdoc = new DartDoc(inputDir, excludeLibraries, sdkDir, generators,
       outputDir, packageMeta, includeLibraries,
@@ -218,6 +219,10 @@ ArgParser _createArgsParser() {
       help: 'Group libraries from the same package into categories.',
       negatable: false,
       defaultsTo: false);
+  parser.addFlag('auto-include-dependencies',
+      help: 'Include all the used libraries into the docs, even the ones not in the current package or "include-external"',
+      negatable: false,
+      defaultsTo: false);
   return parser;
 }
 

lib/dartdoc.dart

@@ -67,14 +67,16 @@ void initializeConfig(
     bool showWarnings: false,
     bool addCrossdart: false,
     String examplePathPrefix,
-    bool includeSource: true}) {
+    bool includeSource: true,
+    bool autoIncludeDependencies: false}) {
   setConfig(
       inputDir: inputDir,
       sdkVersion: sdkVersion,
       showWarnings: showWarnings,
       addCrossdart: addCrossdart,
       examplePathPrefix: examplePathPrefix,
-      includeSource: includeSource);
+      includeSource: includeSource,
+      autoIncludeDependencies: autoIncludeDependencies);
 }
 
 Map<String, List<fileSystem.Folder>> _calculatePackageMap(
@@ -150,6 +152,13 @@ class DartDoc {
     }
 
     Package package = new Package(libraries, packageMeta);
+
+    if (config != null && config.autoIncludeDependencies) {
+      final newLibraryElements = _buildLibrariesWithAutoincludedDependencies(package);
+      Library.clearLibraryMap();
+      package = new Package(newLibraryElements, packageMeta);
+    }
+
     // Go through docs of every model element in package to prebuild the macros index
     package.allModelElements.forEach((m) => m.documentation);
 
@@ -358,3 +367,24 @@ class _Error implements Comparable<_Error> {
   @override
   String toString() => '[${severityName}] ${description}';
 }
+
+Iterable<LibraryElement> _buildLibrariesWithAutoincludedDependencies(Package package) {
+  final List<LibraryElement> newLibraryElements = []..addAll(package.libraries.map((l) => l.element as LibraryElement));
+
+  package.allModelElements.forEach((modelElement) {
+    modelElement.usedElements.forEach((used) {
+      if (used != null && used.modelType != null) {
+        final ModelElement modelTypeElement = used.modelType.element;
+        final library = package.findLibraryFor(modelTypeElement.element);
+        if (library == null && modelTypeElement.library != null) {
+          if (!newLibraryElements.contains(modelTypeElement.library.element)
+              && !modelTypeElement.library.name.startsWith("dart:")) {
+            newLibraryElements.add(modelTypeElement.library.element);
+          }
+        }
+      }
+    });
+  });
+
+  return newLibraryElements;
+}

lib/src/config.dart

@@ -13,8 +13,15 @@ class Config {
   final String examplePathPrefix;
   final bool includeSource;
   final String sdkVersion;
+  final bool autoIncludeDependencies;
   Config._(
-      this.inputDir, this.showWarnings, this.addCrossdart, this.examplePathPrefix, this.includeSource, this.sdkVersion);
+      this.inputDir,
+      this.showWarnings,
+      this.addCrossdart,
+      this.examplePathPrefix,
+      this.includeSource,
+      this.sdkVersion,
+      this.autoIncludeDependencies);
 }
 
 Config _config;
@@ -26,6 +33,14 @@ void setConfig(
     String sdkVersion,
     bool addCrossdart: false,
     String examplePathPrefix,
-    bool includeSource: true}) {
-  _config = new Config._(inputDir, showWarnings, addCrossdart, examplePathPrefix, includeSource, sdkVersion);
+    bool includeSource: true,
+    bool autoIncludeDependencies: false}) {
+  _config = new Config._(
+      inputDir,
+      showWarnings,
+      addCrossdart,
+      examplePathPrefix,
+      includeSource,
+      sdkVersion,
+      autoIncludeDependencies);
 }

lib/src/element_type.dart

@@ -64,7 +64,7 @@ class ElementType {
 
   ModelElement get returnElement {
     Element e = _returnTypeCore.element;
-    if (e == null) {
+    if (e == null || e.library == null) {
       return null;
     }
     Library lib = element.package.findLibraryFor(e);

lib/src/model.dart

@@ -961,7 +961,10 @@ abstract class GetterSetterCombo {
 }
 
 class Library extends ModelElement {
-  static final Map<String, Library> _libraryMap = <String, Library>{};
+  static Map<String, Library> _libraryMap = <String, Library>{};
+  static void clearLibraryMap() {
+    _libraryMap = {};
+  }
 
   @override
   final Package package;
@@ -1771,6 +1774,31 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
     return builder.toString().trim();
   }
 
+  /// Gather all the used elements, from the parameters and return type, for example
+  /// E.g. method <code>Iterable<String> blah(List<int> foo)</code> will return
+  /// <code>[Iterable, String, List, int]</code>
+  Iterable<ModelElement> get usedElements {
+    final set = new Set<ModelElement>();
+    if (modelType != null) {
+      if (modelType.isFunctionType) {
+        if (modelType.returnElement != null) {
+          set.addAll(modelType.returnElement.usedElements);
+        }
+        if (canHaveParameters) {
+          set.addAll(parameters.map((p) => p.usedElements).expand((i) => i));
+        }
+      } else if (modelType.element != null) {
+        set.add(modelType.element);
+        if (modelType.isParameterizedType) {
+          set.addAll(modelType.typeArguments
+              .map((arg) => arg.element.usedElements)
+              .expand((i) => i));
+        }
+      }
+    }
+    return set;
+  }
+
   @override
   String toString() => '$runtimeType $name';
 

test/compare_output_test.dart

@@ -50,6 +50,7 @@ void main() {
 
       var args = <String>[
         dartdocBin,
+        '--auto-include-dependencies',
         '--example-path-prefix',
         'examples',
         '--no-include-source',

test/model_test.dart

@@ -625,7 +625,7 @@ void main() {
     });
 
     test('inherited methods, including from Object ', () {
-      expect(B.inheritedMethods, hasLength(6));
+      expect(B.inheritedMethods, hasLength(7));
       expect(B.hasInheritedMethods, isTrue);
     });
 

testing/test_package/lib/example.dart

@@ -4,6 +4,7 @@ library ex;
 import 'dart:async';
 
 import 'src/mylib.dart' show Helper;
+import 'package:test_package_imported/main.dart';
 
 export 'dart:core' show deprecated, Deprecated;
 
@@ -97,6 +98,10 @@ class Apple {
 
   Apple._internal(this._s2);
 
+  /// Apple docs for whataclass
+  void whataclass(List<Whataclass<bool>> list) {
+  }
+
   /**
    * The getter for `s`
    */

testing/test_package/pubspec.lock

@@ -1,5 +1,11 @@
 # Generated by pub
 # See http://pub.dartlang.org/doc/glossary.html#lockfile
-packages: {}
+packages:
+  test_package_imported:
+    description:
+      path: "../test_package_imported"
+      relative: true
+    source: path
+    version: "0.0.1"
 sdks:
   dart: any