Allow injected HTML in a macro which is output by a tool (#2274)

Process directives after macro-processing

Author: srawlins

lib/src/model/comment_processable.dart

@@ -913,7 +913,11 @@ class PackageGraph {
   }
 
   void addMacro(String name, String content) {
-    assert(!_localDocumentationBuilt);
+    // TODO(srawlins): We have to add HTML fragments after documentation is
+    // built, in order to include fragments which come from macros which
+    // were generated by a tool. I think the macro/HTML-injection system needs
+    // to be overhauled to allow for this type of looping.
+    //assert(!_localDocumentationBuilt);
     _macros[name] = content;
   }
 
@@ -923,7 +927,11 @@ class PackageGraph {
   }
 
   void addHtmlFragment(String name, String content) {
-    assert(!_localDocumentationBuilt);
+    // TODO(srawlins): We have to add HTML fragments after documentation is
+    // built, in order to include fragments which come from macros which
+    // were generated by a tool. I think the macro/HTML-injection system needs
+    // to be overhauled to allow for this type of looping.
+    //assert(!_localDocumentationBuilt);
     _htmlFragments[name] = content;
   }
 }

lib/src/model/model_element.dart

@@ -266,6 +266,18 @@ void main() {
       expect(injectHtmlFromTool.documentationAsHtml,
           isNot(contains('{@end-inject-html}')));
     });
+    test('tool outputs a macro which outputs injected HTML', () {
+      var ToolPrintingMacroWhichInjectsHtml = injectionExLibrary.allClasses
+          .firstWhere((c) => c.name == 'ToolPrintingMacroWhichInjectsHtml');
+      var a = ToolPrintingMacroWhichInjectsHtml.instanceFields
+          .firstWhere((m) => m.name == 'a');
+      expect(a.documentationAsHtml,
+          contains('<p>Text.</p>\n<p><div class="title">Title</div></p>'));
+      var b = ToolPrintingMacroWhichInjectsHtml.instanceFields
+          .firstWhere((m) => m.name == 'b');
+      expect(b.documentationAsHtml,
+          contains('<p>Text.</p>\n<p><div class="title">Title</div></p>'));
+    });
   });
 
   group('Missing and Remote', () {

lib/src/model/package_graph.dart

@@ -1617,7 +1617,7 @@ void main() {
     });
 
     test('correctly finds all the classes', () {
-      expect(classes, hasLength(33));
+      expect(classes, hasLength(34));
     });
 
     test('abstract', () {

test/model_special_cases_test.dart

@@ -0,0 +1,10 @@
+// Copyright (c) 2020, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+// This is a sample "tool" used to test external tool integration into dartdoc.
+// It has no other purpose.
+
+void main() {
+  print('{@macro html-macro}');
+}

test/model_test.dart

@@ -11,6 +11,9 @@ dartdoc:
     drill:
       command: ["bin/drill.dart"]
       description: "Puts holes in things."
+    print_macro:
+      command: ["bin/print_macro.dart"]
+      description: "Prints a macro."
     echo:
       macos: ['/bin/sh', '-c', 'echo']
       linux: ['/bin/sh', '-c', 'echo']

testing/test_package/bin/print_macro.dart

@@ -200,16 +200,14 @@ class Apple {
   final ParameterizedTypedef<bool> fieldWithTypedef;
 }
 
-
 /// Extension on Apple
 extension AppleExtension on Apple {
-/// Can call s on Apple
+  /// Can call s on Apple
   void s() {
     print('Extension on Apple');
   }
 }
 
-
 class WithGeneric<T> {
   T prop;
   WithGeneric(this.prop);
@@ -666,15 +664,15 @@ class ExtensionUser {
 /// Extension on List
 extension FancyList<Z> on List<Z> {
   int get doubleLength => this.length * 2;
-  List<Z> operator-() => this.reversed.toList();
+  List<Z> operator -() => this.reversed.toList();
   List<List<Z>> split(int at) =>
       <List<Z>>[this.sublist(0, at), this.sublist(at)];
   static List<Z> big() => List(1000000);
 }
 
 extension SymDiff<Q> on Set<Q> {
   Set<Q> symmetricDifference(Set<Q> other) =>
-    this.difference(other).union(other.difference(this));
+      this.difference(other).union(other.difference(this));
 }
 
 /// Extensions can be made specific.
@@ -684,16 +682,30 @@ extension IntSet on Set<int> {
 
 // Extensions can be private.
 extension _Shhh on Object {
-  void secret() { }
+  void secret() {}
 }
 
 // Extension with no name
 extension on Object {
-  void bar() { }
+  void bar() {}
 }
 
-
 /// This class has nothing to do with [_Shhh], [FancyList], or [AnExtension.call],
 /// but should not crash because we referenced them.
 /// We should be able to find [DocumentThisExtensionOnce], too.
 class ExtensionReferencer {}
+
+class ToolPrintingMacroWhichInjectsHtml {
+  /// Text.
+  /// {@template html-macro}
+  /// {@inject-html}<div class="title">Title</div>{@end-inject-html}
+  /// {@endtemplate}
+  int a;
+
+  /// Text.
+  ///
+  /// {@tool print_macro}
+  /// Text for tool.
+  /// {@end-tool}
+  int b;
+}