Add support for injecting HTML (#1792)

* Add support for injecting HTML

* Update docs

Author: gspencergoog

lib/src/model.dart

@@ -39,6 +39,7 @@ import 'package:analyzer/src/dart/element/member.dart'
 import 'package:analyzer/src/dart/analysis/driver.dart';
 import 'package:args/args.dart';
 import 'package:collection/collection.dart';
+import 'package:crypto/crypto.dart';
 import 'package:dartdoc/src/dartdoc_options.dart';
 import 'package:dartdoc/src/element_type.dart';
 import 'package:dartdoc/src/io_utils.dart';
@@ -3142,6 +3143,7 @@ abstract class ModelElement extends Canonicalization
       _rawDocs = _injectExamples(_rawDocs);
       _rawDocs = _injectAnimations(_rawDocs);
       _rawDocs = _stripMacroTemplatesAndAddToIndex(_rawDocs);
+      _rawDocs = _stripHtmlAndAddToIndex(_rawDocs);
     }
     return _rawDocs;
   }
@@ -3287,8 +3289,13 @@ abstract class ModelElement extends Canonicalization
     return false;
   }
 
+  String _htmlDocumentation;
   @override
-  String get documentationAsHtml => _documentation.asHtml;
+  String get documentationAsHtml {
+    if (_htmlDocumentation != null) return _htmlDocumentation;
+    _htmlDocumentation = _injectHtmlFragments(_documentation.asHtml);
+    return _htmlDocumentation;
+  }
 
   @override
   Element get element => _element;
@@ -4047,6 +4054,51 @@ abstract class ModelElement extends Canonicalization
     });
   }
 
+  /// Replace &lt;<dartdoc-html>[digest]</dartdoc-html>&gt; in API comments with
+  /// the contents of the HTML fragment earlier defined by the
+  /// &#123;@inject-html&#125; directive. The [digest] is a SHA1 of the contents
+  /// of the HTML fragment, automatically generated upon parsing the
+  /// &#123;@inject-html&#125; directive.
+  ///
+  /// This markup is generated and inserted by [_stripHtmlAndAddToIndex] when it
+  /// removes the HTML fragment in preparation for markdown processing. It isn't
+  /// meant to be used at a user level.
+  ///
+  /// Example:
+  ///
+  /// You place the fragment in a dartdoc comment:
+  ///
+  ///     Some comments
+  ///     &#123;@inject-html&#125;
+  ///     &lt;p&gt;[HTML contents!]&lt;/p&gt;
+  ///     &#123;@endtemplate&#125;
+  ///     More comments
+  ///
+  /// and [_stripHtmlAndAddToIndex] will replace your HTML fragment with this:
+  ///
+  ///     Some comments
+  ///     &lt;dartdoc-html&gt;4cc02f877240bf69855b4c7291aba8a16e5acce0&lt;/dartdoc-html&gt;
+  ///     More comments
+  ///
+  /// Which will render in the final HTML output as:
+  ///
+  ///     Some comments
+  ///     &lt;p&gt;[HTML contents!]&lt;/p&gt;
+  ///     More comments
+  ///
+  /// And the HTML fragment will not have been processed or changed by Markdown,
+  /// but just injected verbatim.
+  String _injectHtmlFragments(String rawDocs) {
+    final macroRegExp = new RegExp(r'<dartdoc-html>([a-f0-9]+)</dartdoc-html>');
+    return rawDocs.replaceAllMapped(macroRegExp, (match) {
+      String fragment = packageGraph.getHtmlFragment(match[1]);
+      if (fragment == null) {
+        warn(PackageWarning.unknownHtmlFragment, message: match[1]);
+      }
+      return fragment;
+    });
+  }
+
   /// Replace &#123;@macro ...&#125; in API comments with the contents of the macro
   ///
   /// Syntax:
@@ -4084,7 +4136,8 @@ abstract class ModelElement extends Canonicalization
     });
   }
 
-  /// Parse &#123;@template ...&#125; in API comments and store them in the index on the package.
+  /// Parse and remove &#123;@template ...&#125; in API comments and store them
+  /// in the index on the package.
   ///
   /// Syntax:
   ///
@@ -4102,6 +4155,31 @@ abstract class ModelElement extends Canonicalization
     });
   }
 
+  /// 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
+  /// the rest of the text is complete.
+  ///
+  /// Syntax:
+  ///
+  ///     &#123;@inject-html&#125;
+  ///     <p>The HTML to inject.</p>
+  ///     &#123;@end-inject-html&#125;
+  ///
+  String _stripHtmlAndAddToIndex(String rawDocs) {
+    final templateRegExp = new RegExp(
+        r'[ ]*{@inject-html\s*}([\s\S]+?){@end-inject-html}[ ]*\n?',
+        multiLine: true);
+    return rawDocs.replaceAllMapped(templateRegExp, (match) {
+      String fragment = match[1];
+      String digest = sha1.convert(fragment.codeUnits).toString();
+      packageGraph._addHtmlFragment(digest, fragment);
+      // The newlines are so that Markdown will pass this through without
+      // touching it.
+      return '\n<dartdoc-html>$digest</dartdoc-html>\n';
+    });
+  }
+
   /// Helper to process arguments given as a (possibly quoted) string.
   ///
   /// First, this will split the given [argsAsString] into separate arguments,
@@ -4434,7 +4512,7 @@ class PackageGraph {
     // Go through docs of every ModelElement in package to pre-build the macros
     // index.
     allLocalModelElements.forEach((m) => m.documentationLocal);
-    _macrosAdded = true;
+    _localDocumentationBuilt = true;
 
     // Scan all model elements to insure that interceptor and other special
     // objects are found.
@@ -4539,8 +4617,9 @@ class PackageGraph {
 
   final Map<Element, Library> _elementToLibrary = {};
   final Map<String, String> _macros = {};
+  final Map<String, String> _htmlFragments = {};
   bool allLibrariesAdded = false;
-  bool _macrosAdded = false;
+  bool _localDocumentationBuilt = false;
 
   /// Returns true if there's at least one library documented in the package
   /// that has the same package path as the library for the given element.
@@ -4685,6 +4764,9 @@ class PackageGraph {
       case PackageWarning.unknownMacro:
         warningMessage = "undefined macro [${message}]";
         break;
+      case PackageWarning.unknownHtmlFragment:
+        warningMessage = "undefined HTML fragment identifier [${message}]";
+        break;
       case PackageWarning.brokenLink:
         warningMessage = 'dartdoc generated a broken link to: ${message}';
         warnablePrefix = 'to element';
@@ -5165,14 +5247,24 @@ class PackageGraph {
   }
 
   String getMacro(String name) {
-    assert(_macrosAdded);
+    assert(_localDocumentationBuilt);
     return _macros[name];
   }
 
   void _addMacro(String name, String content) {
-    assert(!_macrosAdded);
+    assert(!_localDocumentationBuilt);
     _macros[name] = content;
   }
+
+  String getHtmlFragment(String name) {
+    assert(_localDocumentationBuilt);
+    return _htmlFragments[name];
+  }
+
+  void _addHtmlFragment(String name, String content) {
+    assert(!_localDocumentationBuilt);
+    _htmlFragments[name] = content;
+  }
 }
 
 /// A set of [Class]es, [Enum]s, [TopLevelVariable]s, [ModelFunction]s,
@@ -5887,8 +5979,8 @@ abstract class SourceCodeMixin implements Documentable {
 
   String get _crossdartPath {
     var node = element.computeNode();
-    if (node is Declaration && node.element != null) {
-      var source = node.element.source;
+    if (node is Declaration && node.declaredElement != null) {
+      var source = node.declaredElement.source;
       var filePath = source.fullName;
       var uri = source.uri.toString();
       var packageMeta = library.packageGraph.packageMeta;

lib/src/warnings.dart

@@ -136,6 +136,7 @@ enum PackageWarning {
   reexportedPrivateApiAcrossPackages,
   unresolvedDocReference,
   unknownMacro,
+  unknownHtmlFragment,
   brokenLink,
   orphanedFile,
   unknownFile,

pubspec.lock

@@ -128,7 +128,7 @@ packages:
     source: hosted
     version: "2.0.2"
   crypto:
-    dependency: transitive
+    dependency: "direct main"
     description:
       name: crypto
       url: "https://pub.dartlang.org"

pubspec.yaml

@@ -11,6 +11,7 @@ dependencies:
   analyzer: ^0.33.0
   args: '>=1.4.1 <2.0.0'
   collection: ^1.2.0
+  crypto: ^2.0.6
   html: '>=0.12.1 <0.14.0'
   # We don't use http_parser directly; this dep exists to ensure that we get at
   # least version 3.0.3 to work around an issue with 3.0.2.

test/model_test.dart

@@ -116,6 +116,25 @@ void main() {
     });
   });
 
+  group('HTML Injection', () {
+    Class htmlInjection;
+    Method injectSimpleHtml;
+
+    setUp(() {
+      htmlInjection = exLibrary.classes.firstWhere((c) => c.name == 'HtmlInjection');
+      injectSimpleHtml =
+          htmlInjection.allInstanceMethods.firstWhere((m) => m.name == 'injectSimpleHtml');
+      packageGraph.allLocalModelElements.forEach((m) => m.documentation);
+    });
+    test("can inject HTML", () {
+      expect(
+          injectSimpleHtml.documentation,
+          contains('\n<dartdoc-html>bad2bbdd4a5cf9efb3212afff4449904756851aa</dartdoc-html>\n'));
+      expect(injectSimpleHtml.documentationAsHtml,
+          contains('   <div style="opacity: 0.5;">[HtmlInjection]</div>'));
+    });
+  });
+
   group('Missing and Remote', () {
     test('Verify that SDK libraries are not canonical when missing', () {
       expect(
@@ -1424,7 +1443,7 @@ void main() {
     });
 
     test('correctly finds all the classes', () {
-      expect(classes, hasLength(29));
+      expect(classes, hasLength(30));
     });
 
     test('abstract', () {

test/tool_runner_test.dart

@@ -75,7 +75,7 @@ void main() {
       );
       expect(errors, isNotEmpty);
       expect(
-          errors[0], contains('Tool "drill" returned non-zero exit code (1)'));
+          errors[0], contains('Tool "drill" returned non-zero exit code'));
       expect(result, isEmpty);
     });
     test("fails if tool in tool map doesn't exist", () {

testing/test_package/lib/example.dart

@@ -598,3 +598,11 @@ abstract class ToolUser {
   /// {@end-tool}
   void invokeToolNoInput();
 }
+
+abstract class HtmlInjection {
+  /// Injects some HTML.
+  /// {@inject-html}
+  ///    <div style="opacity: 0.5;">[HtmlInjection]</div>
+  /// {@end-inject-html}
+  void injectSimpleHtml();
+}

testing/test_package_docs/ex/Animal-class.html

@@ -55,6 +55,7 @@ <h5>ex library</h5>
       <li><a href="ex/ForAnnotation-class.html">ForAnnotation</a></li>
       <li><a href="ex/HasAnnotation-class.html">HasAnnotation</a></li>
       <li><a href="ex/Helper-class.html">Helper</a></li>
+      <li><a href="ex/HtmlInjection-class.html">HtmlInjection</a></li>
       <li><a href="ex/Klass-class.html">Klass</a></li>
       <li><a href="ex/ParameterizedClass-class.html">ParameterizedClass</a></li>
       <li><a href="ex/PublicClassExtendsPrivateClass-class.html">PublicClassExtendsPrivateClass</a></li>

testing/test_package_docs/ex/AnotherParameterizedClass-class.html

@@ -55,6 +55,7 @@ <h5>ex library</h5>
       <li><a href="ex/ForAnnotation-class.html">ForAnnotation</a></li>
       <li><a href="ex/HasAnnotation-class.html">HasAnnotation</a></li>
       <li><a href="ex/Helper-class.html">Helper</a></li>
+      <li><a href="ex/HtmlInjection-class.html">HtmlInjection</a></li>
       <li><a href="ex/Klass-class.html">Klass</a></li>
       <li><a href="ex/ParameterizedClass-class.html">ParameterizedClass</a></li>
       <li><a href="ex/PublicClassExtendsPrivateClass-class.html">PublicClassExtendsPrivateClass</a></li>

testing/test_package_docs/ex/Apple-class.html

@@ -55,6 +55,7 @@ <h5>ex library</h5>
       <li><a href="ex/ForAnnotation-class.html">ForAnnotation</a></li>
       <li><a href="ex/HasAnnotation-class.html">HasAnnotation</a></li>
       <li><a href="ex/Helper-class.html">Helper</a></li>
+      <li><a href="ex/HtmlInjection-class.html">HtmlInjection</a></li>
       <li><a href="ex/Klass-class.html">Klass</a></li>
       <li><a href="ex/ParameterizedClass-class.html">ParameterizedClass</a></li>
       <li><a href="ex/PublicClassExtendsPrivateClass-class.html">PublicClassExtendsPrivateClass</a></li>