Steel thread for new lookup code (#2622)

* Squash the large number of merges

* test tweaks

* Rename comment_reference.dart and get some of the threads through to markdown_processor

* Finalize the first pass of the new lookup code

* Improve stats by ignoring parameter resolution differences in equivalence (parameters can't be linked to)

* more stats tweaks

* first batch of comments

* review comments

* href -> null on parameters

* Fix count yet again

* tweak

Author: jcollins-g

lib/dartdoc.dart

@@ -20,6 +20,7 @@ import 'package:dartdoc/src/generator/generator.dart';
 import 'package:dartdoc/src/generator/html_generator.dart';
 import 'package:dartdoc/src/generator/markdown_generator.dart';
 import 'package:dartdoc/src/logging.dart';
+import 'package:dartdoc/src/markdown_processor.dart' show markdownStats;
 import 'package:dartdoc/src/model/model.dart';
 import 'package:dartdoc/src/package_meta.dart';
 import 'package:dartdoc/src/tool_runner.dart';
@@ -207,6 +208,10 @@ class Dartdoc {
     libs = packageGraph.localPublicLibraries.length;
     logInfo("Documented $libs public librar${libs == 1 ? 'y' : 'ies'} "
         'in ${seconds.toStringAsFixed(1)} seconds');
+
+    if (config.showStats) {
+      logInfo(markdownStats.buildReport());
+    }
     return DartdocResults(config.topLevelPackageMeta, packageGraph, outputDir);
   }
 

lib/src/dartdoc_options.dart

@@ -1496,6 +1496,9 @@ class DartdocOptionContext extends DartdocOptionContextBase
   List<String> get excludePackages =>
       optionSet['excludePackages'].valueAt(context);
 
+  bool get experimentalReferenceLookup =>
+      optionSet['experimentalReferenceLookup'].valueAt(context);
+
   String get flutterRoot => optionSet['flutterRoot'].valueAt(context);
 
   bool get hideSdkText => optionSet['hideSdkText'].valueAt(context);
@@ -1558,6 +1561,8 @@ class DartdocOptionContext extends DartdocOptionContextBase
   bool isPackageExcluded(String name) =>
       excludePackages.any((pattern) => name == pattern);
 
+  bool get showStats => optionSet['showStats'].valueAt(context);
+
   /// Output format, e.g. 'html', 'md'
   String get format => optionSet['format'].valueAt(context);
 
@@ -1627,6 +1632,12 @@ Future<List<DartdocOption<Object>>> createDartdocOptions(
         help: 'Library names to ignore.', splitCommas: true),
     DartdocOptionArgOnly<List<String>>('excludePackages', [], resourceProvider,
         help: 'Package names to ignore.', splitCommas: true),
+    DartdocOptionArgFile<bool>(
+        'experimentalReferenceLookup', false, resourceProvider,
+        hide: true,
+        help:
+            'Use an experimental code path to resolve comment reference lookups',
+        negatable: true),
     // This could be a ArgOnly, but trying to not provide too many ways
     // to set the flutter root.
     DartdocOptionSyntheticOnly<String>(
@@ -1799,6 +1810,8 @@ Future<List<DartdocOption<Object>>> createDartdocOptions(
             'pages, and please file an issue on GitHub.',
         negatable: false,
         hide: true),
+    DartdocOptionArgOnly<bool>('showStats', false, resourceProvider,
+        help: 'Show statistics useful for debugging.', hide: true),
     // TODO(jdkoren): Unhide when we have good support for another format.
     DartdocOptionArgOnly<String>('format', 'html', resourceProvider,
         hide: true),

lib/src/element_type.dart

@@ -8,15 +8,17 @@ library dartdoc.element_type;
 import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/dart/element/nullability_suffix.dart';
 import 'package:analyzer/dart/element/type.dart';
+import 'package:dartdoc/src/model/comment_referable.dart';
 import 'package:dartdoc/src/model/model.dart';
 import 'package:dartdoc/src/render/element_type_renderer.dart';
 
 /// Base class representing a type in Dartdoc.  It wraps a [DartType], and
 /// may link to a [ModelElement].
-abstract class ElementType extends Privacy {
+abstract class ElementType extends Privacy with CommentReferable, Nameable {
   final DartType _type;
   final PackageGraph packageGraph;
   final ElementType returnedFrom;
+  @override
   final Library library;
 
   ElementType(this._type, this.library, this.packageGraph, this.returnedFrom);
@@ -73,8 +75,6 @@ abstract class ElementType extends Privacy {
 
   String get linkedName;
 
-  String get name;
-
   /// Name with generics and nullability indication.
   String get nameWithGenerics;
 
@@ -113,6 +113,9 @@ class UndefinedElementType extends ElementType {
       ElementType returnedFrom)
       : super(f, library, packageGraph, returnedFrom);
 
+  @override
+  Element get element => null;
+
   String _linkedName;
 
   @override
@@ -131,7 +134,7 @@ class UndefinedElementType extends ElementType {
   bool get isImpliedFuture => (type.isDynamic &&
       returnedFrom != null &&
       returnedFrom is DefinedElementType &&
-      (returnedFrom as DefinedElementType).element.isAsynchronous);
+      (returnedFrom as DefinedElementType).modelElement.isAsynchronous);
 
   @override
   String get nameWithGenerics => '$name$nullabilitySuffix';
@@ -153,6 +156,12 @@ class UndefinedElementType extends ElementType {
   @override
   String get linkedName => name;
 
+  @override
+  Map<String, CommentReferable> get referenceChildren => {};
+
+  @override
+  Iterable<CommentReferable> get referenceParents => [];
+
   @override
   // TODO(jcollins-g): remove the need for an empty list here.
   List<Parameter> get parameters => [];
@@ -264,15 +273,18 @@ class TypeParameterElementType extends DefinedElementType {
 
 /// An [ElementType] associated with an [Element].
 abstract class DefinedElementType extends ElementType {
-  final ModelElement _element;
+  final ModelElement _modelElement;
 
   DefinedElementType(DartType type, Library library, PackageGraph packageGraph,
-      this._element, ElementType returnedFrom)
+      this._modelElement, ElementType returnedFrom)
       : super(type, library, packageGraph, returnedFrom);
 
-  ModelElement get element {
-    assert(_element != null);
-    return _element;
+  @override
+  Element get element => modelElement.element;
+
+  ModelElement get modelElement {
+    assert(_modelElement != null);
+    return _modelElement;
   }
 
   @override
@@ -285,20 +297,21 @@ abstract class DefinedElementType extends ElementType {
   /// would ordinarily do.
   @override
   bool get isPublic {
-    Container canonicalClass =
-        element.packageGraph.findCanonicalModelElementFor(element.element) ??
-            element;
-    return canonicalClass.isPublic;
+    Container canonicalClass = modelElement.packageGraph
+            .findCanonicalModelElementFor(modelElement.element) ??
+        modelElement;
+    return canonicalClass?.isPublic ?? false;
   }
 
   @override
-  bool get isTypedef => element is Typedef || element is ModelFunctionTypedef;
+  bool get isTypedef =>
+      modelElement is Typedef || modelElement is ModelFunctionTypedef;
 
   @override
   List<Parameter> get parameters =>
-      element.isCallable ? element.parameters : [];
+      modelElement.isCallable ? modelElement.parameters : [];
 
-  ModelElement get returnElement => element;
+  ModelElement get returnElement => modelElement;
   ElementType _returnType;
   ElementType get returnType {
     _returnType ??= ElementType.from(type, library, packageGraph, this);
@@ -359,14 +372,22 @@ abstract class DefinedElementType extends ElementType {
     }
     return false;
   }
+
+  @override
+  Map<String, CommentReferable> get referenceChildren =>
+      modelElement.referenceChildren;
+
+  @override
+  Iterable<CommentReferable> get referenceParents =>
+      modelElement.referenceParents;
 }
 
 /// Any callable ElementType will mix-in this class, whether anonymous or not.
 abstract class CallableElementTypeMixin implements ElementType {
   Iterable<ElementType> _typeArguments;
 
   ModelElement get returnElement => returnType is DefinedElementType
-      ? (returnType as DefinedElementType).element
+      ? (returnType as DefinedElementType).modelElement
       : null;
 
   ElementType _returnType;