Store comment reference data on ModelNode (#3797)

This is work towards #3798.

The analyzer is now tagging Comment nodes with references with various static elements, all backed by the new @docImport syntax, via a new DocImportScope (see https://dart-review.googlesource.com/c/sdk/+/345361 and https://dart-review.googlesource.com/c/sdk/+/353232). But they're not available in the element model. So while we have the syntax nodes, in PackageGraph, we must "side-car" the data, by storing it in separate classes (with no references to any AST nodes).

So in this change we introduce the CommentReferenceData class, attach instances to ModelNode.

Author: srawlins

lib/src/model/model_node.dart

@@ -11,15 +11,22 @@ import 'package:analyzer/dart/element/element.dart';
 import 'package:meta/meta.dart';
 
 /// Stripped down information derived from [AstNode] containing only information
-/// needed to resurrect the source code of [element].
+/// needed to resurrect the source code of [_element].
 class ModelNode {
   final Element _element;
   final AnalysisContext _analysisContext;
   final int _sourceEnd;
   final int _sourceOffset;
 
+  /// Data about each comment reference found in the doc comment of this node.
+  final Map<String, CommentReferenceData>? commentReferenceData;
+
   factory ModelNode(
-      AstNode? sourceNode, Element element, AnalysisContext analysisContext) {
+    AstNode? sourceNode,
+    Element element,
+    AnalysisContext analysisContext, {
+    required Map<String, CommentReferenceData>? commentReferenceData,
+  }) {
     if (sourceNode == null) {
       return ModelNode._(element, analysisContext,
           sourceEnd: -1, sourceOffset: -1);
@@ -32,14 +39,23 @@ class ModelNode {
         assert(sourceNode is FieldDeclaration ||
             sourceNode is TopLevelVariableDeclaration);
       }
-      return ModelNode._(element, analysisContext,
-          sourceEnd: sourceNode.end, sourceOffset: sourceNode.offset);
+      return ModelNode._(
+        element,
+        analysisContext,
+        sourceEnd: sourceNode.end,
+        sourceOffset: sourceNode.offset,
+        commentReferenceData: commentReferenceData,
+      );
     }
   }
 
-  ModelNode._(this._element, this._analysisContext,
-      {required int sourceEnd, required int sourceOffset})
-      : _sourceEnd = sourceEnd,
+  ModelNode._(
+    this._element,
+    this._analysisContext, {
+    required int sourceEnd,
+    required int sourceOffset,
+    this.commentReferenceData = const {},
+  })  : _sourceEnd = sourceEnd,
         _sourceOffset = sourceOffset;
 
   bool get _isSynthetic => _sourceEnd < 0 || _sourceOffset < 0;
@@ -63,6 +79,20 @@ class ModelNode {
   }();
 }
 
+/// Comment reference data from the syntax tree.
+///
+/// Comment reference data is not available on the analyzer's Element model, so
+/// we store it after resolving libraries in instances of this class.
+class CommentReferenceData {
+  final Element element;
+  final String name;
+  final int offset;
+  final int length;
+
+  CommentReferenceData(this.element, String? name, this.offset, this.length)
+      : name = name ?? '';
+}
+
 @visibleForTesting
 extension SourceStringExtensions on String {
   String substringFromLineStart(int offset, int endOffset) {

lib/src/model/package_graph.dart

@@ -5,11 +5,12 @@
 import 'dart:collection';
 
 import 'package:analyzer/dart/analysis/analysis_context.dart';
-import 'package:analyzer/dart/ast/ast.dart';
 import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/file_system/file_system.dart';
 import 'package:analyzer/source/source.dart';
 // ignore: implementation_imports
+import 'package:analyzer/src/dart/ast/ast.dart';
+// ignore: implementation_imports
 import 'package:analyzer/src/dart/element/inheritance_manager3.dart'
     show InheritanceManager3;
 // ignore: implementation_imports
@@ -234,6 +235,20 @@ class PackageGraph with CommentReferable, Nameable {
   // me how, because the data is on AST nodes, not the element model.
   void gatherModelNodes(DartDocResolvedLibrary resolvedLibrary) {
     for (var unit in resolvedLibrary.units) {
+      for (var directive in unit.directives.whereType<LibraryDirective>()) {
+        // There should be only one library directive. If there are more, there
+        // is no harm in grabbing ModelNode for each.
+        var commentReferenceData = directive.documentationComment?.data;
+        _modelNodes.putIfAbsent(
+            resolvedLibrary.element,
+            () => ModelNode(
+                  directive,
+                  resolvedLibrary.element,
+                  analysisContext,
+                  commentReferenceData: commentReferenceData,
+                ));
+      }
+
       for (var declaration in unit.declarations) {
         _populateModelNodeFor(declaration);
         switch (declaration) {
@@ -243,6 +258,9 @@ class PackageGraph with CommentReferable, Nameable {
             }
           case EnumDeclaration():
             if (declaration.declaredElement?.isPublic ?? false) {
+              for (var constant in declaration.constants) {
+                _populateModelNodeFor(constant);
+              }
               for (var member in declaration.members) {
                 _populateModelNodeFor(member);
               }
@@ -269,12 +287,21 @@ class PackageGraph with CommentReferable, Nameable {
   }
 
   void _populateModelNodeFor(Declaration declaration) {
+    var commentReferenceData = declaration.documentationComment?.data;
+
     if (declaration is FieldDeclaration) {
       var fields = declaration.fields.variables;
       for (var field in fields) {
         var element = field.declaredElement!;
         _modelNodes.putIfAbsent(
-            element, () => ModelNode(field, element, analysisContext));
+          element,
+          () => ModelNode(
+            field,
+            element,
+            analysisContext,
+            commentReferenceData: commentReferenceData,
+          ),
+        );
       }
       return;
     }
@@ -283,13 +310,27 @@ class PackageGraph with CommentReferable, Nameable {
       for (var field in fields) {
         var element = field.declaredElement!;
         _modelNodes.putIfAbsent(
-            element, () => ModelNode(field, element, analysisContext));
+          element,
+          () => ModelNode(
+            field,
+            element,
+            analysisContext,
+            commentReferenceData: commentReferenceData,
+          ),
+        );
       }
       return;
     }
     var element = declaration.declaredElement!;
     _modelNodes.putIfAbsent(
-        element, () => ModelNode(declaration, element, analysisContext));
+      element,
+      () => ModelNode(
+        declaration,
+        element,
+        analysisContext,
+        commentReferenceData: commentReferenceData,
+      ),
+    );
   }
 
   ModelNode? getModelNodeFor(Element element) => _modelNodes[element];
@@ -1029,3 +1070,41 @@ class InheritableElementsKey {
 
   InheritableElementsKey(this.element, this.library);
 }
+
+extension on Comment {
+  /// A mapping of all comment references to their various data.
+  Map<String, CommentReferenceData> get data {
+    if (references.isEmpty) return const {};
+
+    var data = <String, CommentReferenceData>{};
+    for (var reference in references) {
+      var commentReferable = reference.expression;
+      String name;
+      Element? staticElement;
+      if (commentReferable case PropertyAccessImpl(:var propertyName)) {
+        var target = commentReferable.target;
+        if (target is! PrefixedIdentifierImpl) continue;
+        name = '${target.name}.${propertyName.name}';
+        staticElement = propertyName.staticElement;
+      } else if (commentReferable case PrefixedIdentifier(:var identifier)) {
+        name = commentReferable.name;
+        staticElement = identifier.staticElement;
+      } else if (commentReferable case SimpleIdentifier()) {
+        name = commentReferable.name;
+        staticElement = commentReferable.staticElement;
+      } else {
+        continue;
+      }
+
+      if (staticElement != null && !data.containsKey(name)) {
+        data[name] = CommentReferenceData(
+          staticElement,
+          name,
+          commentReferable.offset,
+          commentReferable.length,
+        );
+      }
+    }
+    return data;
+  }
+}

test/dartdoc_test_base.dart

@@ -154,4 +154,11 @@ $libraryContent
     );
     return await Dartdoc.fromContext(context, packageBuilder);
   }
+
+  /// The real offset in a library generated with [bootPackageWithLibrary].
+  ///
+  /// When a library is written via [bootPackageWithLibrary], the test author
+  /// provides `libraryContent`, which is a snippet of Dart library text.
+  int realOffsetFor(int offsetInContent) =>
+      '\n\nlibrary $libraryName\n\n'.length + offsetInContent;
 }