From a9bd874c8664f121600e697ae1d812cbef266982 Mon Sep 17 00:00:00 2001
From: Sam Rawlins <srawlins@google.com>
Date: Wed, 26 Jun 2024 17:56:17 -0700
Subject: [PATCH 1/3] WIP use docImports

---
 lib/src/model/documentation_comment.dart | 29 ++++++++-
 lib/src/model/model_node.dart            | 35 +++++++++--
 lib/src/model/package_graph.dart         | 76 ++++++++++++------------
 test/documentation_comment_test.dart     | 53 +++++++++++------
 test/model_node_test.dart                | 14 ++---
 5 files changed, 135 insertions(+), 72 deletions(-)

diff --git a/lib/src/model/documentation_comment.dart b/lib/src/model/documentation_comment.dart
index 1365373f26..3a16039dde 100644
--- a/lib/src/model/documentation_comment.dart
+++ b/lib/src/model/documentation_comment.dart
@@ -111,7 +111,7 @@ mixin DocumentationComment
   /// Process [documentationComment], performing various actions based on
   /// `{@}`-style directives, returning the processed result.
   @visibleForTesting
-  Future<String> processComment(String documentationComment) async {
+  Future<String> processComment(/*String documentationComment*/) async {
     var docs = stripComments(documentationComment);
     // Must evaluate tools first, in case they insert any other directives.
     docs = await _evaluateTools(docs);
@@ -121,6 +121,7 @@ mixin DocumentationComment
   }
 
   String processCommentDirectives(String docs) {
+    docs = _stripDocImports(docs);
     // The vast, vast majority of doc comments have no directives.
     if (!docs.contains('{@')) {
       return docs;
@@ -557,6 +558,30 @@ mixin DocumentationComment
     });
   }
 
+  String _stripDocImports(String content) {
+    if (modelNode?.commentData case var commentData?) {
+      var buffer = StringBuffer();
+      if (commentData.docImports.isEmpty) return content;
+      var firstDocImport = commentData.docImports.first;
+      print(
+          'FIRST DOC COMMENT: ${firstDocImport.offset} for ${firstDocImport.length}: '
+          '"${content.substring(0, firstDocImport.offset)}"');
+      buffer.write(content.substring(0, firstDocImport.offset));
+      var offset = firstDocImport.offset + firstDocImport.length;
+      for (var docImport in commentData.docImports.skip(1)) {
+        print('NEXT DOC COMMENT: ${docImport.offset} for ${docImport.length}: '
+            '"${content.substring(0, docImport.offset)}"');
+        buffer.write(content.substring(offset, docImport.offset));
+        offset = docImport.offset + docImport.length;
+      }
+      // Write from the end of the last doc-import to the end of the comment.
+      buffer.write(content.substring(offset));
+      return buffer.toString();
+    } else {
+      return content;
+    }
+  }
+
   /// Parse and remove &#123;@inject-html ...&#125; in API comments and store
   /// them in the index on the package, replacing them with a SHA1 hash of the
   /// contents, where the HTML will be re-injected after Markdown processing of
@@ -793,7 +818,7 @@ mixin DocumentationComment
     assert(_rawDocs == null,
         'reentrant calls to _buildDocumentation* not allowed');
     // Do not use the sync method if we need to evaluate tools or templates.
-    var rawDocs = await processComment(documentationComment);
+    var rawDocs = await processComment();
     return _rawDocs = buildDocumentationAddition(rawDocs);
   }
 
diff --git a/lib/src/model/model_node.dart b/lib/src/model/model_node.dart
index 50d65abd12..f75933870e 100644
--- a/lib/src/model/model_node.dart
+++ b/lib/src/model/model_node.dart
@@ -18,14 +18,14 @@ class ModelNode {
   final int _sourceEnd;
   final int _sourceOffset;
 
-  /// Data about each comment reference found in the doc comment of this node.
-  final Map<String, CommentReferenceData>? commentReferenceData;
+  /// Data about the doc comment of this node.
+  final CommentData? commentData;
 
   factory ModelNode(
     AstNode? sourceNode,
     Element element,
     AnalysisContext analysisContext, {
-    required Map<String, CommentReferenceData>? commentReferenceData,
+    CommentData? commentData,
   }) {
     if (sourceNode == null) {
       return ModelNode._(element, analysisContext,
@@ -44,7 +44,7 @@ class ModelNode {
         analysisContext,
         sourceEnd: sourceNode.end,
         sourceOffset: sourceNode.offset,
-        commentReferenceData: commentReferenceData,
+        commentData: commentData,
       );
     }
   }
@@ -54,7 +54,7 @@ class ModelNode {
     this._analysisContext, {
     required int sourceEnd,
     required int sourceOffset,
-    this.commentReferenceData = const {},
+    this.commentData,
   })  : _sourceEnd = sourceEnd,
         _sourceOffset = sourceOffset;
 
@@ -79,10 +79,33 @@ class ModelNode {
   }();
 }
 
+/// Comment data from the syntax tree.
+///
+/// Various comment data is not available on the analyzer's Element model, so we
+/// store it in instances of this class after resolving libraries.
+class CommentData {
+  final List<CommentDocImportData> docImports;
+  final Map<String, CommentReferenceData> references;
+
+  CommentData({required this.docImports, required this.references});
+}
+
+/// doc-import data from the syntax tree.
+///
+/// Comment doc-import data is not available on the analyzer's Element model, so
+/// we store it in instances of this class after resolving libraries.
+class CommentDocImportData {
+  final int offset;
+
+  final int length;
+
+  CommentDocImportData({required this.offset, required this.length});
+}
+
 /// 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.
+/// we store it in instances of this class after resolving libraries.
 class CommentReferenceData {
   final Element element;
   final String name;
diff --git a/lib/src/model/package_graph.dart b/lib/src/model/package_graph.dart
index b0d06033c7..0c3b0d501b 100644
--- a/lib/src/model/package_graph.dart
+++ b/lib/src/model/package_graph.dart
@@ -238,14 +238,17 @@ class PackageGraph with CommentReferable, Nameable {
       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;
+        var commentData = directive.documentationComment?.data;
+        directive.documentationComment?.docDirectives;
+        directive.documentationComment?.docImports;
+        directive.documentationComment?.hasNodoc;
         _modelNodes.putIfAbsent(
             resolvedLibrary.element,
             () => ModelNode(
                   directive,
                   resolvedLibrary.element,
                   analysisContext,
-                  commentReferenceData: commentReferenceData,
+                  commentData: commentData,
                 ));
       }
 
@@ -287,50 +290,39 @@ class PackageGraph with CommentReferable, Nameable {
   }
 
   void _populateModelNodeFor(Declaration declaration) {
-    var commentReferenceData = declaration.documentationComment?.data;
+    var commentData = declaration.documentationComment?.data;
+
+    void addModelNode(Declaration declaration) {
+      var element = declaration.declaredElement;
+      if (element == null) {
+        throw StateError("Expected '$declaration' to declare an element");
+      }
+      _modelNodes.putIfAbsent(
+        element,
+        () => ModelNode(
+          declaration,
+          element,
+          analysisContext,
+          commentData: commentData,
+        ),
+      );
+    }
 
     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,
-            commentReferenceData: commentReferenceData,
-          ),
-        );
+        addModelNode(field);
       }
       return;
     }
     if (declaration is TopLevelVariableDeclaration) {
       var fields = declaration.variables.variables;
       for (var field in fields) {
-        var element = field.declaredElement!;
-        _modelNodes.putIfAbsent(
-          element,
-          () => ModelNode(
-            field,
-            element,
-            analysisContext,
-            commentReferenceData: commentReferenceData,
-          ),
-        );
+        addModelNode(field);
       }
       return;
     }
-    var element = declaration.declaredElement!;
-    _modelNodes.putIfAbsent(
-      element,
-      () => ModelNode(
-        declaration,
-        element,
-        analysisContext,
-        commentReferenceData: commentReferenceData,
-      ),
-    );
+    addModelNode(declaration);
   }
 
   ModelNode? getModelNodeFor(Element element) => _modelNodes[element];
@@ -1073,10 +1065,16 @@ class InheritableElementsKey {
 
 extension on Comment {
   /// A mapping of all comment references to their various data.
-  Map<String, CommentReferenceData> get data {
-    if (references.isEmpty) return const {};
+  CommentData get data {
+    var docImportsData = <CommentDocImportData>[];
+    for (var docImport in docImports) {
+      docImportsData.add(
+        CommentDocImportData(
+            offset: docImport.offset, length: docImport.import.length),
+      );
+    }
 
-    var data = <String, CommentReferenceData>{};
+    var referencesData = <String, CommentReferenceData>{};
     for (var reference in references) {
       var commentReferable = reference.expression;
       String name;
@@ -1096,8 +1094,8 @@ extension on Comment {
         continue;
       }
 
-      if (staticElement != null && !data.containsKey(name)) {
-        data[name] = CommentReferenceData(
+      if (staticElement != null && !referencesData.containsKey(name)) {
+        referencesData[name] = CommentReferenceData(
           staticElement,
           name,
           commentReferable.offset,
@@ -1105,6 +1103,6 @@ extension on Comment {
         );
       }
     }
-    return data;
+    return CommentData(docImports: docImportsData, references: referencesData);
   }
 }
diff --git a/test/documentation_comment_test.dart b/test/documentation_comment_test.dart
index cdad6b2be0..b50b991b65 100644
--- a/test/documentation_comment_test.dart
+++ b/test/documentation_comment_test.dart
@@ -28,14 +28,11 @@ class DocumentationCommentTest extends DartdocTestBase {
   late ModelElement libraryModel;
 
   void expectNoWarnings() {
-    expect(packageGraph.packageWarningCounter.hasWarnings, isFalse);
     expect(packageGraph.packageWarningCounter.countedWarnings, isEmpty);
+    expect(packageGraph.packageWarningCounter.hasWarnings, isFalse);
   }
 
-  @override
-  Future<void> setUp() async {
-    await super.setUp();
-
+  Future<void> writeLibraryWithComment(String comment) async {
     projectRoot = utils.writePackage(
         'my_package', resourceProvider, packageConfigProvider);
     projectRoot
@@ -50,8 +47,8 @@ class DocumentationCommentTest extends DartdocTestBase {
         .getChildAssumingFolder('lib')
         .getChildAssumingFile('a.dart')
         .writeAsStringSync('''
-/// Documentation comment.
-int x = 1;
+$comment
+library;
 ''');
 
     var optionSet = DartdocOptionRoot.fromOptionGenerators(
@@ -64,10 +61,11 @@ int x = 1;
   }
 
   void test_removesTripleSlashes() async {
-    var doc = await libraryModel.processComment('''
+    await writeLibraryWithComment('''
 /// Text.
 /// More text.
 ''');
+    var doc = await libraryModel.processComment();
 
     expect(doc, equals('''
 Text.
@@ -75,10 +73,11 @@ More text.'''));
   }
 
   void test_removesSpaceAfterTripleSlashes() async {
-    var doc = await libraryModel.processComment('''
+    await writeLibraryWithComment('''
 ///  Text.
 ///    More text.
 ''');
+    var doc = await libraryModel.processComment();
 
     // TODO(srawlins): Actually, the three spaces before 'More' is perhaps not
     // the best fit. Should it only be two, to match the indent from the first
@@ -89,11 +88,12 @@ Text.
   }
 
   void test_leavesBlankLines() async {
-    var doc = await libraryModel.processComment('''
+    await writeLibraryWithComment('''
 /// Text.
 ///
 /// More text.
 ''');
+    var doc = await libraryModel.processComment();
 
     expect(doc, equals('''
 Text.
@@ -101,14 +101,15 @@ Text.
 More text.'''));
   }
 
-  void test_processesAanimationDirective() async {
-    var doc = await libraryModel.processComment('''
+  void test_processesAnimationDirective() async {
+    await writeLibraryWithComment('''
 /// Text.
 ///
 /// {@animation 100 200 http://host/path/to/video.mp4 id=barHerderAnimation}
 ///
 /// End text.
 ''');
+    var doc = await libraryModel.processComment();
 
     expectNoWarnings();
     expect(doc, equals('''
@@ -153,39 +154,42 @@ End text.'''));
   }
 
   void test_rendersUnnamedAnimation() async {
-    var doc = await libraryModel.processComment('''
+    await writeLibraryWithComment('''
 /// First line.
 ///
 /// {@animation 100 200 http://host/path/to/video.mp4}
 ''');
+    var doc = await libraryModel.processComment();
 
     expectNoWarnings();
     expect(doc, contains('<video id="animation_1"'));
   }
 
   void test_rendersNamedAnimation() async {
-    var doc = await libraryModel.processComment('''
+    await writeLibraryWithComment('''
 /// First line.
 ///
 /// {@animation 100 200 http://host/path/to/video.mp4 id=namedAnimation}
 ''');
+    var doc = await libraryModel.processComment();
 
     expectNoWarnings();
     expect(doc, contains('<video id="namedAnimation"'));
   }
 
   void test_rendersNamedAnimation_outOfOrder() async {
-    var doc = await libraryModel.processComment('''
+    await writeLibraryWithComment('''
 /// First line.
 ///
 /// {@animation 100 200 id=namedAnimation http://host/path/to/video.mp4}
 ''');
+    var doc = await libraryModel.processComment();
 
     expectNoWarnings();
     expect(doc, contains('<video id="namedAnimation"'));
   }
 
-  void test_rendersNamedAnimationWithDoubleQuotes() async {
+  /*void test_rendersNamedAnimationWithDoubleQuotes() async {
     var doc = await libraryModel.processComment('''
 /// First line.
 ///
@@ -229,10 +233,23 @@ End text.'''));
 
     expectNoWarnings();
     expect(doc, contains('<video id="animation_3"'));
+    expect(doc, contains('<video id="animation_4"'));
+  }*/
+
+  void solo_test_docImport() async {
+    await writeLibraryWithComment('''
+/// Text.
+///
+/// @docImport 'dart:async' as async;
+///
+/// End text.
+''');
+    var doc = await libraryModel.processComment();
+
     expect(doc, contains('<video id="animation_4"'));
   }
 
-  void test_animationDirectiveHasFewerThanThreeArguments() async {
+  /*void test_animationDirectiveHasFewerThanThreeArguments() async {
     await libraryModel.processComment('''
 /// Text.
 ///
@@ -696,7 +713,7 @@ Text.
             PackageWarning.missingCodeBlockLanguage,
             'A fenced code block in Markdown should have a language specified'),
         isFalse);
-  }
+  }*/
 
   Matcher hasDeprecatedWarning(String message) =>
       _HasWarning(PackageWarning.deprecated, message);
diff --git a/test/model_node_test.dart b/test/model_node_test.dart
index a8f86d60ca..2000c42d7d 100644
--- a/test/model_node_test.dart
+++ b/test/model_node_test.dart
@@ -27,7 +27,7 @@ class C {}
 ''');
     var c = library.classes.named('C');
     expect(c.name, equals('C'));
-    var commentReferenceData = c.modelNode!.commentReferenceData!;
+    var commentReferenceData = c.modelNode!.commentData!.references;
     expect(
       commentReferenceData['int'],
       isA<CommentReferenceData>()
@@ -47,7 +47,7 @@ class C {}
 ''');
     var c = library.classes.named('C');
     expect(c.name, equals('C'));
-    var commentReferenceData = c.modelNode!.commentReferenceData!;
+    var commentReferenceData = c.modelNode!.commentData!.references;
     expect(
       commentReferenceData['FutureOr'],
       isA<CommentReferenceData>()
@@ -65,7 +65,7 @@ class C {}
 ''');
     var c = library.classes.named('C');
     expect(c.name, equals('C'));
-    var commentReferenceData = c.modelNode!.commentReferenceData!;
+    var commentReferenceData = c.modelNode!.commentData!.references;
     expect(
       commentReferenceData['async.Future.value'],
       isA<CommentReferenceData>()
@@ -82,7 +82,7 @@ class C {}
 ''');
     var c = library.classes.named('C');
     expect(c.name, equals('C'));
-    var commentReferenceData = c.modelNode!.commentReferenceData!;
+    var commentReferenceData = c.modelNode!.commentData!.references;
     expect(
       commentReferenceData['Future.value'],
       isA<CommentReferenceData>()
@@ -101,7 +101,7 @@ class C {
 ''');
     var g = library.classes.named('C').instanceAccessors.named('g');
     expect(g.name, equals('g'));
-    var commentReferenceData = g.modelNode!.commentReferenceData!;
+    var commentReferenceData = g.modelNode!.commentData!.references;
     expect(
       commentReferenceData['int'],
       isA<CommentReferenceData>()
@@ -118,7 +118,7 @@ int a = 1, b = 2;
 ''');
     var a = library.properties.named('a');
     expect(a.name, equals('a'));
-    var aData = a.modelNode!.commentReferenceData!;
+    var aData = a.modelNode!.commentData!.references;
     expect(
       aData['int'],
       isA<CommentReferenceData>()
@@ -129,7 +129,7 @@ int a = 1, b = 2;
 
     var b = library.properties.named('b');
     expect(b.name, equals('b'));
-    var bData = b.modelNode!.commentReferenceData!;
+    var bData = b.modelNode!.commentData!.references;
     expect(
       bData['int'],
       isA<CommentReferenceData>()

From 62f052139988152252f5cfd9d25a8d4589f1b410 Mon Sep 17 00:00:00 2001
From: Sam Rawlins <srawlins@google.com>
Date: Thu, 27 Jun 2024 22:16:08 -0700
Subject: [PATCH 2/3] Parse and remove doc-imports from comment text

---
 lib/src/model/accessor.dart              |   2 +-
 lib/src/model/documentation_comment.dart |  31 +-
 lib/src/model/model_node.dart            |  14 +-
 lib/src/model/package_graph.dart         |   5 +-
 lib/src/utils.dart                       |   3 +-
 test/documentation_comment_test.dart     | 454 ++++++++++++++---------
 test/utils_test.dart                     |  16 +-
 7 files changed, 325 insertions(+), 200 deletions(-)

diff --git a/lib/src/model/accessor.dart b/lib/src/model/accessor.dart
index 30d77d2b56..0a251507f5 100644
--- a/lib/src/model/accessor.dart
+++ b/lib/src/model/accessor.dart
@@ -72,7 +72,7 @@ class Accessor extends ModelElement {
     }
     // TODO(srawlins): This doesn't seem right... the super value has delimiters
     // (like `///`), but this one doesn't?
-    return stripComments(super.documentationComment);
+    return stripCommentDelimiters(super.documentationComment);
   }();
 
   /// If this is a getter, assume we want synthetic documentation.
diff --git a/lib/src/model/documentation_comment.dart b/lib/src/model/documentation_comment.dart
index 3a16039dde..7f0047244a 100644
--- a/lib/src/model/documentation_comment.dart
+++ b/lib/src/model/documentation_comment.dart
@@ -96,7 +96,10 @@ mixin DocumentationComment
   /// `{@}`-style directives (except tool directives), returning the processed
   /// result.
   String _processCommentWithoutTools(String documentationComment) {
-    var docs = stripComments(documentationComment);
+    // We must first strip the comment of directives like `@docImport`, since
+    // the offsets are for the source text.
+    var docs = _stripDocImports(documentationComment);
+    docs = stripCommentDelimiters(docs);
     if (docs.contains('{@')) {
       docs = _injectYouTube(docs);
       docs = _injectAnimations(docs);
@@ -111,9 +114,13 @@ mixin DocumentationComment
   /// Process [documentationComment], performing various actions based on
   /// `{@}`-style directives, returning the processed result.
   @visibleForTesting
-  Future<String> processComment(/*String documentationComment*/) async {
-    var docs = stripComments(documentationComment);
-    // Must evaluate tools first, in case they insert any other directives.
+  Future<String> processComment() async {
+    // We must first strip the comment of directives like `@docImport`, since
+    // the offsets are for the source text.
+    var docs = _stripDocImports(documentationComment);
+    docs = stripCommentDelimiters(docs);
+    // Then we evaluate tools, in case they insert any other directives that
+    // would need to be processed by `processCommentDirectives`.
     docs = await _evaluateTools(docs);
     docs = processCommentDirectives(docs);
     _analyzeCodeBlocks(docs);
@@ -121,7 +128,6 @@ mixin DocumentationComment
   }
 
   String processCommentDirectives(String docs) {
-    docs = _stripDocImports(docs);
     // The vast, vast majority of doc comments have no directives.
     if (!docs.contains('{@')) {
       return docs;
@@ -560,19 +566,16 @@ mixin DocumentationComment
 
   String _stripDocImports(String content) {
     if (modelNode?.commentData case var commentData?) {
+      var commentOffset = commentData.offset;
       var buffer = StringBuffer();
       if (commentData.docImports.isEmpty) return content;
       var firstDocImport = commentData.docImports.first;
-      print(
-          'FIRST DOC COMMENT: ${firstDocImport.offset} for ${firstDocImport.length}: '
-          '"${content.substring(0, firstDocImport.offset)}"');
-      buffer.write(content.substring(0, firstDocImport.offset));
-      var offset = firstDocImport.offset + firstDocImport.length;
+      buffer.write(content.substring(0, firstDocImport.offset - commentOffset));
+      var offset = firstDocImport.end - commentOffset;
       for (var docImport in commentData.docImports.skip(1)) {
-        print('NEXT DOC COMMENT: ${docImport.offset} for ${docImport.length}: '
-            '"${content.substring(0, docImport.offset)}"');
-        buffer.write(content.substring(offset, docImport.offset));
-        offset = docImport.offset + docImport.length;
+        buffer
+            .write(content.substring(offset, docImport.offset - commentOffset));
+        offset = docImport.end - commentOffset;
       }
       // Write from the end of the last doc-import to the end of the comment.
       buffer.write(content.substring(offset));
diff --git a/lib/src/model/model_node.dart b/lib/src/model/model_node.dart
index f75933870e..b21db3f50a 100644
--- a/lib/src/model/model_node.dart
+++ b/lib/src/model/model_node.dart
@@ -84,10 +84,16 @@ class ModelNode {
 /// Various comment data is not available on the analyzer's Element model, so we
 /// store it in instances of this class after resolving libraries.
 class CommentData {
+  /// The offset of this comment in the source text.
+  final int offset;
   final List<CommentDocImportData> docImports;
   final Map<String, CommentReferenceData> references;
 
-  CommentData({required this.docImports, required this.references});
+  CommentData({
+    required this.offset,
+    required this.docImports,
+    required this.references,
+  });
 }
 
 /// doc-import data from the syntax tree.
@@ -95,11 +101,13 @@ class CommentData {
 /// Comment doc-import data is not available on the analyzer's Element model, so
 /// we store it in instances of this class after resolving libraries.
 class CommentDocImportData {
+  /// The offset of the doc import in the source text.
   final int offset;
 
-  final int length;
+  /// The offset of the end of the doc import in the source text.
+  final int end;
 
-  CommentDocImportData({required this.offset, required this.length});
+  CommentDocImportData({required this.offset, required this.end});
 }
 
 /// Comment reference data from the syntax tree.
diff --git a/lib/src/model/package_graph.dart b/lib/src/model/package_graph.dart
index 0c3b0d501b..dc90185cdf 100644
--- a/lib/src/model/package_graph.dart
+++ b/lib/src/model/package_graph.dart
@@ -1070,7 +1070,7 @@ extension on Comment {
     for (var docImport in docImports) {
       docImportsData.add(
         CommentDocImportData(
-            offset: docImport.offset, length: docImport.import.length),
+            offset: docImport.offset, end: docImport.import.end),
       );
     }
 
@@ -1103,6 +1103,7 @@ extension on Comment {
         );
       }
     }
-    return CommentData(docImports: docImportsData, references: referencesData);
+    return CommentData(
+        offset: offset, docImports: docImportsData, references: referencesData);
   }
 }
diff --git a/lib/src/utils.dart b/lib/src/utils.dart
index 0630dff3b1..66babb42a0 100644
--- a/lib/src/utils.dart
+++ b/lib/src/utils.dart
@@ -30,7 +30,8 @@ Iterable<String> stripCommonWhitespace(String str) sync* {
   }
 }
 
-String stripComments(String str) {
+/// Strips [str] of all comment delimiters.
+String stripCommentDelimiters(String str) {
   if (str.isEmpty) return '';
   final buf = StringBuffer();
 
diff --git a/test/documentation_comment_test.dart b/test/documentation_comment_test.dart
index b50b991b65..e9701a1a78 100644
--- a/test/documentation_comment_test.dart
+++ b/test/documentation_comment_test.dart
@@ -32,7 +32,10 @@ class DocumentationCommentTest extends DartdocTestBase {
     expect(packageGraph.packageWarningCounter.hasWarnings, isFalse);
   }
 
-  Future<void> writeLibraryWithComment(String comment) async {
+  Future<void> writePackageWithCommentedLibraries(
+    List<(String, String)> filesAndComments, {
+    List<String> additionalArguments = const [],
+  }) async {
     projectRoot = utils.writePackage(
         'my_package', resourceProvider, packageConfigProvider);
     projectRoot
@@ -43,29 +46,36 @@ class DocumentationCommentTest extends DartdocTestBase {
           - missing-code-block-language
       ''');
 
-    projectRoot
-        .getChildAssumingFolder('lib')
-        .getChildAssumingFile('a.dart')
-        .writeAsStringSync('''
-$comment
-library;
-''');
+    for (var (fileName, comment) in filesAndComments) {
+      projectRoot
+          .getChildAssumingFolder('lib')
+          .getChildAssumingFile(fileName)
+          .writeAsStringSync('$comment\n'
+              'library;');
+    }
 
     var optionSet = DartdocOptionRoot.fromOptionGenerators(
         'dartdoc', [createDartdocOptions], packageMetaProvider);
     optionSet.parseArguments([]);
     packageGraph = await utils.bootBasicPackage(
         projectRoot.path, packageMetaProvider, packageConfigProvider,
-        additionalArguments: []);
+        additionalArguments: additionalArguments);
     libraryModel = packageGraph.defaultPackage.libraries.first;
   }
 
+  Future<void> writePackageWithCommentedLibrary(
+    String comment, {
+    List<String> additionalArguments = const [],
+  }) =>
+      writePackageWithCommentedLibraries([('a.dart', comment)],
+          additionalArguments: additionalArguments);
+
   void test_removesTripleSlashes() async {
-    await writeLibraryWithComment('''
+    await writePackageWithCommentedLibrary('''
 /// Text.
 /// More text.
 ''');
-    var doc = await libraryModel.processComment();
+    var doc = libraryModel.documentation;
 
     expect(doc, equals('''
 Text.
@@ -73,11 +83,11 @@ More text.'''));
   }
 
   void test_removesSpaceAfterTripleSlashes() async {
-    await writeLibraryWithComment('''
+    await writePackageWithCommentedLibrary('''
 ///  Text.
 ///    More text.
 ''');
-    var doc = await libraryModel.processComment();
+    var doc = libraryModel.documentation;
 
     // TODO(srawlins): Actually, the three spaces before 'More' is perhaps not
     // the best fit. Should it only be two, to match the indent from the first
@@ -88,12 +98,12 @@ Text.
   }
 
   void test_leavesBlankLines() async {
-    await writeLibraryWithComment('''
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// More text.
 ''');
-    var doc = await libraryModel.processComment();
+    var doc = libraryModel.documentation;
 
     expect(doc, equals('''
 Text.
@@ -102,14 +112,14 @@ More text.'''));
   }
 
   void test_processesAnimationDirective() async {
-    await writeLibraryWithComment('''
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// {@animation 100 200 http://host/path/to/video.mp4 id=barHerderAnimation}
 ///
 /// End text.
 ''');
-    var doc = await libraryModel.processComment();
+    var doc = libraryModel.documentation;
 
     expectNoWarnings();
     expect(doc, equals('''
@@ -154,103 +164,175 @@ End text.'''));
   }
 
   void test_rendersUnnamedAnimation() async {
-    await writeLibraryWithComment('''
+    await writePackageWithCommentedLibrary('''
 /// First line.
 ///
 /// {@animation 100 200 http://host/path/to/video.mp4}
 ''');
-    var doc = await libraryModel.processComment();
+    var doc = libraryModel.documentation;
 
     expectNoWarnings();
     expect(doc, contains('<video id="animation_1"'));
   }
 
   void test_rendersNamedAnimation() async {
-    await writeLibraryWithComment('''
+    await writePackageWithCommentedLibrary('''
 /// First line.
 ///
 /// {@animation 100 200 http://host/path/to/video.mp4 id=namedAnimation}
 ''');
-    var doc = await libraryModel.processComment();
+    var doc = libraryModel.documentation;
 
     expectNoWarnings();
     expect(doc, contains('<video id="namedAnimation"'));
   }
 
   void test_rendersNamedAnimation_outOfOrder() async {
-    await writeLibraryWithComment('''
+    await writePackageWithCommentedLibrary('''
 /// First line.
 ///
 /// {@animation 100 200 id=namedAnimation http://host/path/to/video.mp4}
 ''');
-    var doc = await libraryModel.processComment();
+    var doc = libraryModel.documentation;
 
     expectNoWarnings();
     expect(doc, contains('<video id="namedAnimation"'));
   }
 
-  /*void test_rendersNamedAnimationWithDoubleQuotes() async {
-    var doc = await libraryModel.processComment('''
+  void test_rendersNamedAnimationWithDoubleQuotes() async {
+    await writePackageWithCommentedLibrary('''
 /// First line.
 ///
 /// {@animation 100 200 http://host/path/to/video.mp4 id="namedAnimation"}
 ''');
+    var doc = libraryModel.documentation;
 
     expectNoWarnings();
     expect(doc, contains('<video id="namedAnimation"'));
   }
 
   void test_rendersNamedAnimationWithSingleQuotes() async {
-    var doc = await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// First line.
 ///
 /// {@animation 100 200 http://host/path/to/video.mp4 id='namedAnimation'}
 ''');
+    var doc = libraryModel.documentation;
 
     expectNoWarnings();
     expect(doc, contains('<video id="namedAnimation"'));
   }
 
   void test_rendersMultipleAnimationsUsingUniqueIds() async {
-    var doc = await libraryModel.processComment('''
+    await writePackageWithCommentedLibraries([
+      (
+        'a.dart',
+        '''
 /// First line.
 ///
 /// {@animation 100 200 http://host/path/to/video.mp4}
 /// {@animation 100 200 http://host/path/to/video2.mp4}
-''');
-
-    expectNoWarnings();
-    expect(doc, contains('<video id="animation_1"'));
-    expect(doc, contains('<video id="animation_2"'));
-
-    // A second element with unnamed animations requires unique IDs as well.
-    doc = await libraryModel.processComment('''
+''',
+      ),
+      // A second element with unnamed animations requires unique IDs as well.
+      (
+        'b.dart',
+        '''
 /// First line.
 ///
 /// {@animation 100 200 http://host/path/to/video.mp4}
 /// {@animation 100 200 http://host/path/to/video2.mp4}
-''');
+''',
+      ),
+    ]);
+    var docA = await libraryModel.processComment();
+    var docB = packageGraph.defaultPackage.libraries[1].documentation;
 
     expectNoWarnings();
-    expect(doc, contains('<video id="animation_3"'));
-    expect(doc, contains('<video id="animation_4"'));
-  }*/
+    expect(docA, contains('<video id="animation_3"'));
+    expect(docA, contains('<video id="animation_4"'));
+    expect(docB, contains('<video id="animation_1"'));
+    expect(docB, contains('<video id="animation_2"'));
+  }
 
-  void solo_test_docImport() async {
-    await writeLibraryWithComment('''
+  void test_docImport() async {
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// @docImport 'dart:async' as async;
 ///
 /// End text.
 ''');
-    var doc = await libraryModel.processComment();
+    var doc = libraryModel.documentation;
 
-    expect(doc, contains('<video id="animation_4"'));
+    expect(doc, equals('''
+Text.
+
+
+
+End text.'''));
+  }
+
+  void test_docImport_onlyLine() async {
+    await writePackageWithCommentedLibrary('''
+/// @docImport 'dart:async' as async;
+''');
+    var doc = libraryModel.documentation;
+
+    expect(doc, equals(''));
   }
 
-  /*void test_animationDirectiveHasFewerThanThreeArguments() async {
-    await libraryModel.processComment('''
+  void test_docImport_onlyLine_moreWhitespace() async {
+    await writePackageWithCommentedLibrary('''
+///   @docImport   'dart:async'   as   async;
+''');
+    var doc = libraryModel.documentation;
+
+    expect(doc, equals(''));
+  }
+
+  void test_docImport_consecutiveLines() async {
+    await writePackageWithCommentedLibrary('''
+/// @docImport 'dart:async' as async;
+/// @docImport 'dart:isolate' as isolate;
+/// @docImport 'dart:math' as math;
+''');
+    var doc = libraryModel.documentation;
+
+    expect(doc, equals(''));
+  }
+
+  void test_docImport_multipleLines() async {
+    await writePackageWithCommentedLibrary('''
+/// One.
+/// @docImport 'dart:async' as async;
+/// Two.
+/// @docImport 'dart:isolate' as isolate;
+/// Three.
+''');
+    var doc = libraryModel.documentation;
+
+    expect(doc, equals('''
+One.
+
+Two.
+
+Three.'''));
+  }
+
+  void test_docImport_precedingText() async {
+    await writePackageWithCommentedLibrary('''
+// Copyright such-and-such.
+
+/// @docImport 'dart:async' as async;
+''');
+    var doc = libraryModel.documentation;
+
+    expect(doc, equals(''));
+  }
+
+  void test_animationDirectiveHasFewerThanThreeArguments() async {
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// {@animation 100 http://host/path/to/video.mp4 id=barHerderAnimation}
@@ -259,16 +341,17 @@ End text.'''));
 ''');
 
     expect(
-        libraryModel,
-        hasInvalidParameterWarning(
-            'Invalid @animation directive, "{@animation 100 '
-            'http://host/path/to/video.mp4 id=barHerderAnimation}"\n'
-            'Animation directives must be of the form "{@animation WIDTH '
-            'HEIGHT URL [id=ID]}"'));
+      libraryModel,
+      hasInvalidParameterWarning(
+          'Invalid @animation directive, "{@animation 100 '
+          'http://host/path/to/video.mp4 id=barHerderAnimation}"\n'
+          'Animation directives must be of the form "{@animation WIDTH '
+          'HEIGHT URL [id=ID]}"'),
+    );
   }
 
   void test_animationDirectiveHasMoreThanFourArguments() async {
-    await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// {@animation 100 200 300 400 http://host/path/to/video.mp4 id=barHerderAnimation}
@@ -277,16 +360,17 @@ End text.'''));
 ''');
 
     expect(
-        libraryModel,
-        hasInvalidParameterWarning(
-            'Invalid @animation directive, "{@animation 100 200 300 400 '
-            'http://host/path/to/video.mp4 id=barHerderAnimation}"\n'
-            'Animation directives must be of the form "{@animation WIDTH '
-            'HEIGHT URL [id=ID]}"'));
+      libraryModel,
+      hasInvalidParameterWarning(
+          'Invalid @animation directive, "{@animation 100 200 300 400 '
+          'http://host/path/to/video.mp4 id=barHerderAnimation}"\n'
+          'Animation directives must be of the form "{@animation WIDTH '
+          'HEIGHT URL [id=ID]}"'),
+    );
   }
 
   void test_animationDirectiveHasNonUniqueIdentifier() async {
-    await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// {@animation 100 200 http://host/path/to/video.mp4 id=barHerderAnimation}
@@ -296,13 +380,14 @@ End text.'''));
 ''');
 
     expect(
-        libraryModel,
-        hasInvalidParameterWarning('An animation has a non-unique identifier, '
-            '"barHerderAnimation". Animation identifiers must be unique.'));
+      libraryModel,
+      hasInvalidParameterWarning('An animation has a non-unique identifier, '
+          '"barHerderAnimation". Animation identifiers must be unique.'),
+    );
   }
 
   void test_animationDirectiveHasAnInvalidIdentifier() async {
-    await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// {@animation 100 200 http://host/path/to/video.mp4 id=not-valid}
@@ -311,15 +396,16 @@ End text.'''));
 ''');
 
     expect(
-        libraryModel,
-        hasInvalidParameterWarning(
-            'An animation has an invalid identifier, "not-valid". The '
-            'identifier can only contain letters, numbers and underscores, and '
-            'must not begin with a number.'));
+      libraryModel,
+      hasInvalidParameterWarning(
+          'An animation has an invalid identifier, "not-valid". The '
+          'identifier can only contain letters, numbers and underscores, and '
+          'must not begin with a number.'),
+    );
   }
 
   void test_animationDirectiveHasMalformedWidth() async {
-    await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// {@animation 100px 200 http://host/path/to/video.mp4 id=barHerderAnimation}
@@ -328,14 +414,15 @@ End text.'''));
 ''');
 
     expect(
-        libraryModel,
-        hasInvalidParameterWarning(
-            'An animation has an invalid width (barHerderAnimation), '
-            '"100px". The width must be an integer.'));
+      libraryModel,
+      hasInvalidParameterWarning(
+          'An animation has an invalid width (barHerderAnimation), '
+          '"100px". The width must be an integer.'),
+    );
   }
 
   void test_animationDirectiveHasMalformedHeight() async {
-    await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// {@animation 100 200px http://host/path/to/video.mp4 id=barHerderAnimation}
@@ -344,14 +431,15 @@ End text.'''));
 ''');
 
     expect(
-        libraryModel,
-        hasInvalidParameterWarning(
-            'An animation has an invalid height (barHerderAnimation), '
-            '"200px". The height must be an integer.'));
+      libraryModel,
+      hasInvalidParameterWarning(
+          'An animation has an invalid height (barHerderAnimation), '
+          '"200px". The height must be an integer.'),
+    );
   }
 
   void test_animationDirectiveHasUnknownParameter() async {
-    await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// {@animation 100 200 http://host/path/to/video.mp4 name=barHerderAnimation}
@@ -360,15 +448,16 @@ End text.'''));
 ''');
 
     expect(
-        libraryModel,
-        hasInvalidParameterWarning(
-            'The {@animation ...} directive was called with invalid '
-            'parameters. FormatException: Could not find an option named '
-            '"name".'));
+      libraryModel,
+      hasInvalidParameterWarning(
+          'The {@animation ...} directive was called with invalid '
+          'parameters. FormatException: Could not find an option named '
+          '"name".'),
+    );
   }
 
   void test_processesTemplateDirective() async {
-    var doc = await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// {@template abc}
@@ -377,6 +466,7 @@ End text.'''));
 ///
 /// End text.
 ''');
+    var doc = await libraryModel.processComment();
 
     expectNoWarnings();
     expect(doc, equals('''
@@ -388,13 +478,14 @@ End text.'''));
   }
 
   void test_processesLeadingTemplateDirective() async {
-    var doc = await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// {@template abc}
 /// Template text.
 /// {@endtemplate}
 ///
 /// End text.
 ''');
+    var doc = await libraryModel.processComment();
 
     expectNoWarnings();
     expect(doc, equals('''
@@ -404,13 +495,14 @@ End text.'''));
   }
 
   void test_processesTrailingTemplateDirective() async {
-    var doc = await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// {@template abc}
 /// Template text.
 /// {@endtemplate}
 ''');
+    var doc = await libraryModel.processComment();
 
     expectNoWarnings();
     expect(doc, equals('''
@@ -420,7 +512,7 @@ Text.
   }
 
   void test_processesTemplateDirectiveWithoutBlankLineFollowing() async {
-    var doc = await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// {@template abc}
@@ -428,6 +520,7 @@ Text.
 /// {@endtemplate}
 /// End text.
 ''');
+    var doc = await libraryModel.processComment();
 
     expectNoWarnings();
     expect(doc, equals('''
@@ -438,22 +531,24 @@ End text.'''));
   }
 
   void test_allowsWhitespaceAroundTemplateDirectiveName() async {
-    var doc = await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// {@template    abc    }
 /// Template text.
 /// {@endtemplate}
 ''');
+    var doc = await libraryModel.processComment();
 
     expectNoWarnings();
     expect(doc, equals('{@macro abc}'));
   }
 
   void test_leavesInjectHtmlDirectiveUnprocessedWhenDisabled() async {
-    var doc = await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// {@inject-html}<script></script>{@end-inject-html}
 ''');
+    var doc = libraryModel.documentation;
 
     expectNoWarnings();
     expect(doc, equals('''
@@ -463,11 +558,12 @@ Text.
   }
 
   void test_leavesToolUnprocessedWhenDisabled() async {
-    var doc = await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// {@tool date}{@end-tool}
 ''');
+    var doc = libraryModel.documentation;
 
     expectNoWarnings();
     expect(doc, equals('''
@@ -477,15 +573,16 @@ Text.
   }
 
   void test_processesInjectHtmlDirectiveWhenEnabled() async {
-    packageGraph = await utils.bootBasicPackage(
-        projectRoot.path, packageMetaProvider, packageConfigProvider,
-        additionalArguments: ['--inject-html']);
-    libraryModel = packageGraph.defaultPackage.libraries.first;
-    var doc = await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary(
+      additionalArguments: ['--inject-html'],
+      '''
 /// Text.
 ///
 /// {@inject-html}<script></script>{@end-inject-html}
-''');
+''',
+    );
+    libraryModel = packageGraph.defaultPackage.libraries.first;
+    var doc = libraryModel.documentation;
 
     expectNoWarnings();
     expect(doc, equals('''
@@ -497,13 +594,14 @@ Text.
   }
 
   void test_processesYoutubeDirective() async {
-    var doc = await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// {@youtube 100 200 https://www.youtube.com/watch?v=oHg5SJYRHA0}
 ///
 /// End text.
 ''');
+    var doc = libraryModel.documentation;
 
     expectNoWarnings();
     expect(
@@ -521,11 +619,12 @@ Text.
   }
 
   void test_processesLeadingYoutubeDirective() async {
-    var doc = await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// {@youtube 100 200 https://www.youtube.com/watch?v=oHg5SJYRHA0}
 ///
 /// End text.
 ''');
+    var doc = libraryModel.documentation;
 
     expectNoWarnings();
     expect(
@@ -542,11 +641,12 @@ Text.
   }
 
   void test_processesTrailingYoutubeDirective() async {
-    var doc = await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// Text.
 ///
 /// {@youtube 100 200 https://www.youtube.com/watch?v=oHg5SJYRHA0}
 ''');
+    var doc = libraryModel.documentation;
 
     expectNoWarnings();
     expect(
@@ -563,157 +663,169 @@ Text.
   }
 
   void test_youtubeDirectiveHasLessThanThreeArguments() async {
-    await libraryModel.processComment(
+    await writePackageWithCommentedLibrary(
         '/// {@youtube 100 https://www.youtube.com/watch?v=oHg5SJYRHA0}');
 
     expect(
-        libraryModel,
-        hasInvalidParameterWarning('Invalid @youtube directive, '
-            '"{@youtube 100 https://www.youtube.com/watch?v=oHg5SJYRHA0}"\n'
-            'YouTube directives must be of the form '
-            '"{@youtube WIDTH HEIGHT URL}"'));
+      libraryModel,
+      hasInvalidParameterWarning('Invalid @youtube directive, '
+          '"{@youtube 100 https://www.youtube.com/watch?v=oHg5SJYRHA0}"\n'
+          'YouTube directives must be of the form '
+          '"{@youtube WIDTH HEIGHT URL}"'),
+    );
   }
 
   void test_youtubeDirectiveHasMoreThanThreeArguments() async {
-    await libraryModel.processComment(
+    await writePackageWithCommentedLibrary(
         '/// {@youtube 100 200 300 https://www.youtube.com/watch?v=oHg5SJYRHA0}');
 
     expect(
-        libraryModel,
-        hasInvalidParameterWarning('Invalid @youtube directive, '
-            '"{@youtube 100 200 300 https://www.youtube.com/watch?v=oHg5SJYRHA0}"\n'
-            'YouTube directives must be of the form '
-            '"{@youtube WIDTH HEIGHT URL}"'));
+      libraryModel,
+      hasInvalidParameterWarning('Invalid @youtube directive, '
+          '"{@youtube 100 200 300 https://www.youtube.com/watch?v=oHg5SJYRHA0}"\n'
+          'YouTube directives must be of the form '
+          '"{@youtube WIDTH HEIGHT URL}"'),
+    );
   }
 
   void test_youtubeDirectiveHasMalformedWidth() async {
-    await libraryModel.processComment(
+    await writePackageWithCommentedLibrary(
         '/// {@youtube 100px 200 https://www.youtube.com/watch?v=oHg5SJYRHA0}');
 
     expect(
-        libraryModel,
-        hasInvalidParameterWarning(
-            'A @youtube directive has an invalid width, "100px". '
-            'The width must be a positive integer.'));
+      libraryModel,
+      hasInvalidParameterWarning(
+          'A @youtube directive has an invalid width, "100px". '
+          'The width must be a positive integer.'),
+    );
   }
 
   void test_youtubeDirectiveHasNegativeWidth() async {
-    await libraryModel.processComment(
+    await writePackageWithCommentedLibrary(
         '/// {@youtube -100 200 https://www.youtube.com/watch?v=oHg5SJYRHA0}');
 
     expect(
-        libraryModel,
-        hasInvalidParameterWarning(
-            'The {@youtube ...} directive was called with invalid '
-            'parameters. FormatException: Could not find an option with '
-            'short name "-1".'));
+      libraryModel,
+      hasInvalidParameterWarning(
+          'The {@youtube ...} directive was called with invalid '
+          'parameters. FormatException: Could not find an option with '
+          'short name "-1".'),
+    );
   }
 
   void test_youtubeDirectiveHasMalformedHeight() async {
-    await libraryModel.processComment(
+    await writePackageWithCommentedLibrary(
         '/// {@youtube 100 200px https://www.youtube.com/watch?v=oHg5SJYRHA0}');
 
     expect(
-        libraryModel,
-        hasInvalidParameterWarning(
-            'A @youtube directive has an invalid height, "200px". The height '
-            'must be a positive integer.'));
+      libraryModel,
+      hasInvalidParameterWarning(
+          'A @youtube directive has an invalid height, "200px". The height '
+          'must be a positive integer.'),
+    );
   }
 
   void test_youtubeDirectiveHasNegativeHeight() async {
-    await libraryModel.processComment(
+    await writePackageWithCommentedLibrary(
         '/// {@youtube 100 -200 https://www.youtube.com/watch?v=oHg5SJYRHA0}');
 
     expect(
-        libraryModel,
-        hasInvalidParameterWarning(
-            'The {@youtube ...} directive was called with invalid '
-            'parameters. FormatException: Could not find an option with '
-            'short name "-2".'));
+      libraryModel,
+      hasInvalidParameterWarning(
+          'The {@youtube ...} directive was called with invalid '
+          'parameters. FormatException: Could not find an option with '
+          'short name "-2".'),
+    );
   }
 
   void test_youtubeDirectiveHasInvalidUrl() async {
-    await libraryModel.processComment(
+    await writePackageWithCommentedLibrary(
         '/// {@youtube 100 200 https://www.not-youtube.com/watch?v=oHg5SJYRHA0}');
 
     expect(
-        libraryModel,
-        hasInvalidParameterWarning('A @youtube directive has an invalid URL: '
-            '"https://www.not-youtube.com/watch?v=oHg5SJYRHA0". Supported '
-            'YouTube URLs have the following format: '
-            'https://www.youtube.com/watch?v=oHg5SJYRHA0.'));
+      libraryModel,
+      hasInvalidParameterWarning('A @youtube directive has an invalid URL: '
+          '"https://www.not-youtube.com/watch?v=oHg5SJYRHA0". Supported '
+          'YouTube URLs have the following format: '
+          'https://www.youtube.com/watch?v=oHg5SJYRHA0.'),
+    );
   }
 
   void test_youtubeDirectiveHasUrlWithExtraQueryParameters() async {
-    await libraryModel.processComment(
+    await writePackageWithCommentedLibrary(
         '/// {@youtube 100 200 https://www.not-youtube.com/watch?v=oHg5SJYRHA0&a=1}');
 
     expect(
-        libraryModel,
-        hasInvalidParameterWarning('A @youtube directive has an invalid URL: '
-            '"https://www.not-youtube.com/watch?v=oHg5SJYRHA0&a=1". '
-            'Supported YouTube URLs have the following format: '
-            'https://www.youtube.com/watch?v=oHg5SJYRHA0.'));
+      libraryModel,
+      hasInvalidParameterWarning('A @youtube directive has an invalid URL: '
+          '"https://www.not-youtube.com/watch?v=oHg5SJYRHA0&a=1". '
+          'Supported YouTube URLs have the following format: '
+          'https://www.youtube.com/watch?v=oHg5SJYRHA0.'),
+    );
   }
 
   void test_fencedCodeBlockDoesNotSpecifyLanguage() async {
-    await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// ```
 /// void main() {}
 /// ```
 ''');
 
     expect(
-        packageGraph.packageWarningCounter.hasWarning(
-            libraryModel,
-            PackageWarning.missingCodeBlockLanguage,
-            'A fenced code block in Markdown should have a language specified'),
-        isTrue);
+      packageGraph.packageWarningCounter.hasWarning(
+          libraryModel,
+          PackageWarning.missingCodeBlockLanguage,
+          'A fenced code block in Markdown should have a language specified'),
+      isTrue,
+    );
   }
 
   void test_squigglyFencedCodeBlockDoesNotSpecifyLanguage() async {
-    await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// ~~~
 /// void main() {}
 /// ~~~
 ''');
 
     expect(
-        packageGraph.packageWarningCounter.hasWarning(
-            libraryModel,
-            PackageWarning.missingCodeBlockLanguage,
-            'A fenced code block in Markdown should have a language specified'),
-        isTrue);
+      packageGraph.packageWarningCounter.hasWarning(
+          libraryModel,
+          PackageWarning.missingCodeBlockLanguage,
+          'A fenced code block in Markdown should have a language specified'),
+      isTrue,
+    );
   }
 
   void test_fencedCodeBlockDoesSpecifyLanguage() async {
-    await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// ```dart
 /// void main() {}
 /// ```
 ''');
 
     expect(
-        packageGraph.packageWarningCounter.hasWarning(
-            libraryModel,
-            PackageWarning.missingCodeBlockLanguage,
-            'A fenced code block in Markdown should have a language specified'),
-        isFalse);
+      packageGraph.packageWarningCounter.hasWarning(
+          libraryModel,
+          PackageWarning.missingCodeBlockLanguage,
+          'A fenced code block in Markdown should have a language specified'),
+      isFalse,
+    );
   }
 
   void test_fencedBlockIsNotClosed() async {
-    await libraryModel.processComment('''
+    await writePackageWithCommentedLibrary('''
 /// ```
 /// A not closed fenced code block
 ''');
 
     expect(
-        packageGraph.packageWarningCounter.hasWarning(
-            libraryModel,
-            PackageWarning.missingCodeBlockLanguage,
-            'A fenced code block in Markdown should have a language specified'),
-        isFalse);
-  }*/
+      packageGraph.packageWarningCounter.hasWarning(
+          libraryModel,
+          PackageWarning.missingCodeBlockLanguage,
+          'A fenced code block in Markdown should have a language specified'),
+      isFalse,
+    );
+  }
 
   Matcher hasDeprecatedWarning(String message) =>
       _HasWarning(PackageWarning.deprecated, message);
diff --git a/test/utils_test.dart b/test/utils_test.dart
index a43e3ed345..ba516bc8f9 100644
--- a/test/utils_test.dart
+++ b/test/utils_test.dart
@@ -21,20 +21,20 @@ void main() {
       // Trim the last line.
       .replaceFirst(RegExp('\n$multilineStringMargin\$'), '');
 
-  void expectCorrectDocumentation() =>
-      expect(stripComments(trimMargin(comment)), trimMargin(documentation));
+  void expectCorrectDocumentation() => expect(
+      stripCommentDelimiters(trimMargin(comment)), trimMargin(documentation));
 
   group('///-style', () {
     test('one-line comment', () {
-      expect(stripComments('/// One line.'), equals('One line.'));
+      expect(stripCommentDelimiters('/// One line.'), equals('One line.'));
     });
 
     test('unbuffered one-line comment', () {
-      expect(stripComments('///One line.'), equals('One line.'));
+      expect(stripCommentDelimiters('///One line.'), equals('One line.'));
     });
 
     test('multiple runs with multiline comments', () {
-      expect(stripComments(stripComments('''
+      expect(stripCommentDelimiters(stripCommentDelimiters('''
           /// A line.
           /// * An asterisk
       ''')), equals('A line.\n* An asterisk'));
@@ -99,7 +99,7 @@ void main() {
 
   group('/**-style', () {
     test('multiple runs with cstyle comments', () {
-      expect(stripComments(stripComments('''
+      expect(stripCommentDelimiters(stripCommentDelimiters('''
           /**
            * A line.
            * * An asterisk
@@ -108,11 +108,11 @@ void main() {
     });
 
     test('one-line comment', () {
-      expect(stripComments('/** One line. */'), equals('One line.'));
+      expect(stripCommentDelimiters('/** One line. */'), equals('One line.'));
     });
 
     test('unbuffered one-line comment', () {
-      expect(stripComments('/**One line.*/'), equals('One line.'));
+      expect(stripCommentDelimiters('/**One line.*/'), equals('One line.'));
     });
 
     test('multi-line comment', () {

From c57ff6ae7c00592df4914b01c2f1c52f65037fdc Mon Sep 17 00:00:00 2001
From: Sam Rawlins <srawlins@google.com>
Date: Thu, 27 Jun 2024 22:18:23 -0700
Subject: [PATCH 3/3] tidy

---
 lib/src/model/package_graph.dart | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/lib/src/model/package_graph.dart b/lib/src/model/package_graph.dart
index dc90185cdf..8dead13969 100644
--- a/lib/src/model/package_graph.dart
+++ b/lib/src/model/package_graph.dart
@@ -239,9 +239,6 @@ class PackageGraph with CommentReferable, Nameable {
         // There should be only one library directive. If there are more, there
         // is no harm in grabbing ModelNode for each.
         var commentData = directive.documentationComment?.data;
-        directive.documentationComment?.docDirectives;
-        directive.documentationComment?.docImports;
-        directive.documentationComment?.hasNodoc;
         _modelNodes.putIfAbsent(
             resolvedLibrary.element,
             () => ModelNode(