Add macros support [#1264] (#1320)

This adds pretty primitive macros support.

Usage:

You define the template first:

    /// {@template foo}
    /// Some content
    /// {@endtemplate}

Then you use it like:

    /// Some stuff
    /// {@macro foo}
    /// More stuff

and it will be displayed as:

    /// Some stuff
    /// Some content
    /// More stuff

You can define the template pretty much in any documentable symbol
comments. So, after we build a `Package` object, we go through all the
comments documentation of all the model elements of the package, and
build the index of macros. It's still quite fast, and doesn't increase
the build times e.g. of the Flutter docs dramatically.

So, after that, when we actually build HTML pages, we already have the
index with templates in `Package`, so we can replace `{@macros` entries
with the corresponding contents from `{@template`

Author: astashov

README.md

@@ -93,6 +93,27 @@ authoring doc comments for Dart with `dartdoc`.
 `dartdoc` will not generate documentation for a Dart element and its children that have the
 `@nodoc` tag in the documentation comment.
 
+## Advanced features
+
+### Macros
+
+You can specify "macros", i.e. reusable pieces of documentation. For that, first specify a template
+anywhere in the comments, like:
+
+```
+/// {@template template_name}
+/// Some shared docs
+/// {@endtemplate}
+```
+
+and then you can insert it via `{@macro template_name}`, like
+
+```
+/// Some comment
+/// {@macro template_name}
+/// More comments
+```
+
 ## Issues and bugs
 
 Please file reports on the [GitHub Issue Tracker][].

lib/dartdoc.dart

@@ -150,6 +150,8 @@ class DartDoc {
     }
 
     Package package = new Package(libraries, packageMeta);
+    // Go through docs of every model element in package to prebuild the macros index
+    package.allModelElements.forEach((m) => m.documentation);
 
     // Create the out directory.
     if (!outputDir.existsSync()) outputDir.createSync(recursive: true);

lib/src/model.dart

@@ -1472,6 +1472,8 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
 
     _rawDocs = stripComments(_rawDocs) ?? '';
     _rawDocs = _injectExamples(_rawDocs);
+    _rawDocs = _stripMacroTemplatesAndAddToIndex(_rawDocs);
+    _rawDocs = _injectMacros(_rawDocs);
     return _rawDocs;
   }
 
@@ -1867,6 +1869,55 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
     });
   }
 
+  /// Replace {@macro ...} in API comments with the contents of the macro
+  ///
+  /// Syntax:
+  ///
+  ///     {@macro NAME}
+  ///
+  /// Example:
+  ///
+  /// You define the template anywhere in the comments like:
+  ///
+  ///     {@template foo}
+  ///     Foo contents!
+  ///     {@endtemplate}
+  ///
+  /// and them somewhere use it like this:
+  ///
+  ///     Some comments
+  ///     {@macro foo}
+  ///     More comments
+  ///
+  /// Which will render
+  ///
+  ///     Some comments
+  ///     Foo contents!
+  ///     More comments
+  ///
+  String _injectMacros(String rawDocs) {
+    final macroRegExp = new RegExp(r'{@macro\s+([^}]+)}');
+    return rawDocs.replaceAllMapped(macroRegExp, (match) {
+      return package.getMacro(match[1]);
+    });
+  }
+
+  /// Parse {@template ...} in API comments and store them in the index on the package.
+  ///
+  /// Syntax:
+  ///
+  ///     {@template NAME}
+  ///     The contents of the macro
+  ///     {@endtemplate}
+  ///
+  String _stripMacroTemplatesAndAddToIndex(String rawDocs) {
+    final templateRegExp = new RegExp(r'[ ]*{@template\s+(.+?)}([\s\S]+?){@endtemplate}[ ]*\n?', multiLine: true);
+    return rawDocs.replaceAllMapped(templateRegExp, (match) {
+      package.addMacro(match[1].trim(), match[2].trim());
+      return "";
+    });
+  }
+
   /// Helper for _injectExamples used to process @example arguments.
   /// Returns a map of arguments. The first unnamed argument will have key 'src'.
   /// The computed file path, constructed from 'src' and 'region' will have key
@@ -1899,7 +1950,7 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
       var ext = p.extension(src);
       file = p.join(dir, '$basename-$region$ext$fragExtension');
     }
-    args['file'] = config.examplePathPrefix == null ? file : p.join(config.examplePathPrefix, file);
+    args['file'] = config?.examplePathPrefix == null ? file : p.join(config.examplePathPrefix, file);
     return args;
   }
 }
@@ -2020,6 +2071,7 @@ class Package implements Nameable, Documentable {
   final PackageMeta packageMeta;
   final Map<String, Library> elementLibaryMap = {};
   String _docsAsHtml;
+  final Map<String, String> _macros = {};
 
   Package(Iterable<LibraryElement> libraryElements, this.packageMeta) {
     libraryElements.forEach((element) {
@@ -2172,6 +2224,12 @@ class Package implements Nameable, Documentable {
   ExportGraph get exportGraph {
     return (_exportGraph ??= new ExportGraph(libraries.map((l) => l.element as LibraryElement)));
   }
+
+  String getMacro(String name) => _macros[name];
+
+  void addMacro(String name, String content) {
+    _macros[name] = content;
+  }
 }
 
 class PackageCategory implements Comparable<PackageCategory> {

test/model_test.dart

@@ -203,6 +203,26 @@ void main() {
     });
   });
 
+  group('Macros', () {
+    Class dog;
+    Method withMacro, withMacro2;
+
+    setUp(() {
+      dog = exLibrary.classes.firstWhere((c) => c.name == 'Dog');
+      withMacro = dog.allInstanceMethods.firstWhere((m) => m.name == 'withMacro');
+      withMacro2 = dog.allInstanceMethods.firstWhere((m) => m.name == 'withMacro2');
+      package.allModelElements.forEach((m) => m.documentation);
+    });
+
+    test("renders a macro within the same comment where it's defined", () {
+      expect(withMacro.documentation, equals("Macro method\n\n\nFoo macro content\nMore docs"));
+    });
+
+    test("renders a macro in another method, not the same where it's defined", () {
+      expect(withMacro2.documentation, equals("Foo macro content"));
+    });
+  });
+
   group('Docs as HTML', () {
     Class Apple, B, superAwesomeClass, foo2;
     TopLevelVariable incorrectDocReferenceFromEx;
@@ -596,7 +616,7 @@ void main() {
     });
 
     test('get methods', () {
-      expect(Dog.instanceMethods, hasLength(6));
+      expect(Dog.instanceMethods, hasLength(8));
     });
 
     test('get operators', () {
@@ -645,7 +665,7 @@ void main() {
     });
 
     test('F has many inherited methods', () {
-      expect(F.inheritedMethods, hasLength(9));
+      expect(F.inheritedMethods, hasLength(11));
       expect(
           F.inheritedMethods.map((im) => im.name),
           equals([
@@ -657,7 +677,9 @@ void main() {
             'testGeneric',
             'testGenericMethod',
             'testMethod',
-            'toString'
+            'toString',
+            'withMacro',
+            'withMacro2'
           ]));
     });
 

testing/test_package/lib/example.dart

@@ -249,6 +249,19 @@ class Dog implements Cat, E {
     return [new Apple()];
   }
 
+  /// Macro method
+  ///
+  /// {@template foo}
+  /// Foo macro content
+  /// {@endtemplate}
+  ///
+  /// {@macro foo}
+  /// More docs
+  void withMacro() {}
+
+  /// {@macro foo}
+  void withMacro2() {}
+
   void testGeneric(Map<String, dynamic> args) {}
 
   void testMethod(Iterable it) {}

testing/test_package_docs/ex/Dog-class.html

@@ -366,6 +366,22 @@ <h2>Methods</h2>
           <p>Returns a string representation of this object.</p>
           <div class="features">inherited</div>
         </dd>
+        <dt id="withMacro" class="callable">
+          <span class="name"><a href="ex/Dog/withMacro.html">withMacro</a></span><span class="signature">(<wbr>)
+            <span class="returntype parameter">&#8594; void</span>
+          </span>
+        </dt>
+        <dd>
+          <p>Macro method</p>
+        </dd>
+        <dt id="withMacro2" class="callable">
+          <span class="name"><a href="ex/Dog/withMacro2.html">withMacro2</a></span><span class="signature">(<wbr>)
+            <span class="returntype parameter">&#8594; void</span>
+          </span>
+        </dt>
+        <dd>
+          <p>Foo macro content</p>
+        </dd>
       </dl>
     </section>
 
@@ -406,6 +422,8 @@ <h5>Dog</h5>
       <li><a href="ex/Dog/testGenericMethod.html">testGenericMethod</a></li>
       <li><a href="ex/Dog/testMethod.html">testMethod</a></li>
       <li class="inherited"><a href="ex/Dog/toString.html">toString</a></li>
+      <li><a href="ex/Dog/withMacro.html">withMacro</a></li>
+      <li><a href="ex/Dog/withMacro2.html">withMacro2</a></li>
     </ol>
   </div><!--/.sidebar-offcanvas-->
 

testing/test_package_docs/ex/Dog/Dog.deprecatedCreate.html

@@ -106,6 +106,8 @@ <h5><a href="ex/Dog-class.html">Dog</a></h5>
       <li><a href="ex/Dog/testGenericMethod.html">testGenericMethod</a></li>
       <li><a href="ex/Dog/testMethod.html">testMethod</a></li>
       <li class="inherited"><a href="ex/Dog/toString.html">toString</a></li>
+      <li><a href="ex/Dog/withMacro.html">withMacro</a></li>
+      <li><a href="ex/Dog/withMacro2.html">withMacro2</a></li>
     </ol>
 
   </div><!--/.sidebar-offcanvas-left-->

testing/test_package_docs/ex/Dog/Dog.html

@@ -106,6 +106,8 @@ <h5><a href="ex/Dog-class.html">Dog</a></h5>
       <li><a href="ex/Dog/testGenericMethod.html">testGenericMethod</a></li>
       <li><a href="ex/Dog/testMethod.html">testMethod</a></li>
       <li class="inherited"><a href="ex/Dog/toString.html">toString</a></li>
+      <li><a href="ex/Dog/withMacro.html">withMacro</a></li>
+      <li><a href="ex/Dog/withMacro2.html">withMacro2</a></li>
     </ol>
 
   </div><!--/.sidebar-offcanvas-left-->

testing/test_package_docs/ex/Dog/abstractMethod.html

@@ -105,6 +105,8 @@ <h5><a href="ex/Dog-class.html">Dog</a></h5>
       <li><a href="ex/Dog/testGenericMethod.html">testGenericMethod</a></li>
       <li><a href="ex/Dog/testMethod.html">testMethod</a></li>
       <li class="inherited"><a href="ex/Dog/toString.html">toString</a></li>
+      <li><a href="ex/Dog/withMacro.html">withMacro</a></li>
+      <li><a href="ex/Dog/withMacro2.html">withMacro2</a></li>
     </ol>
 
   </div><!--/.sidebar-offcanvas-->

testing/test_package_docs/ex/Dog/createDog.html

@@ -105,6 +105,8 @@ <h5><a href="ex/Dog-class.html">Dog</a></h5>
       <li><a href="ex/Dog/testGenericMethod.html">testGenericMethod</a></li>
       <li><a href="ex/Dog/testMethod.html">testMethod</a></li>
       <li class="inherited"><a href="ex/Dog/toString.html">toString</a></li>
+      <li><a href="ex/Dog/withMacro.html">withMacro</a></li>
+      <li><a href="ex/Dog/withMacro2.html">withMacro2</a></li>
     </ol>
 
   </div><!--/.sidebar-offcanvas-->