Add --inject-html flag to enable {@inject-html}, and update README.md (#1793)

* Update the README.md to include information about {@inject-html}

* Add the --inject-html command line flag to enable HTML injection.

* Add negatable to --inject-html option

Author: gspencergoog

README.md

@@ -301,6 +301,35 @@ the equivalent of having the following comment in the code:
 /// # `This is the text that will be sent to the tool as input.`
 ```
 
+### Injecting HTML
+
+It happens rarely, but sometimes what you really need is to inject some raw HTML
+into the dartdoc output, without it being subject to Markdown processing
+beforehand. This can be useful when the output of an external tool is HTML, for
+instance. This is where the `{@inject-html}...{@end-inject-html}` tags come in.
+
+For security reasons, the `{@inject-html}` directive will be ignored unless the
+`--inject-html` flag is given on the dartdoc command line.
+
+Since this HTML fragment doesn't undergo Markdown processing, reference links
+and other normal processing won't happen on the contained fragment.
+
+So, this:
+```dart
+  ///     {@inject-html}
+  ///     <p>[The HTML to inject.]()</p>
+  ///     {@end-inject-html}
+```
+
+Will result in this be emitted in its place in the HTML output (notice that the
+markdown link isn't linked).
+```
+<p>[The HTML to inject.]()</p>
+```
+
+It's best to only inject HTML that is self-contained and doesn't depend upon
+other elements on the page, since those may change in future versions of Dartdoc.
+
 ### Auto including dependencies
 
 If `--auto-include-dependencies` flag is provided, dartdoc tries to automatically add

lib/src/dartdoc_options.dart

@@ -541,7 +541,7 @@ class DartdocOptionArgSynth<T> extends DartdocOption<T>
       bool hide = false,
       bool isDir = false,
       bool isFile = false,
-      bool negatable,
+      bool negatable = false,
       bool splitCommas})
       : super._(name, null, help, isDir, isFile, mustExist, null) {
     _hide = hide;
@@ -672,7 +672,7 @@ class DartdocOptionArgOnly<T> extends DartdocOption<T>
       bool hide = false,
       bool isDir = false,
       bool isFile = false,
-      bool negatable,
+      bool negatable = false,
       bool splitCommas})
       : super._(name, defaultsTo, help, isDir, isFile, mustExist, null) {
     _hide = hide;
@@ -707,7 +707,7 @@ class DartdocOptionArgFile<T> extends DartdocOption<T>
       bool hide = false,
       bool isDir = false,
       bool isFile = false,
-      bool negatable,
+      bool negatable = false,
       bool parentDirOverridesChild: false,
       bool splitCommas})
       : super._(name, defaultsTo, help, isDir, isFile, mustExist, null) {
@@ -1045,7 +1045,7 @@ abstract class _DartdocArgOption<T> implements DartdocOption<T> {
           defaultsTo: defaultsTo as bool,
           help: help,
           hide: hide,
-          negatable: negatable);
+          negatable: negatable ?? false);
     } else if (_isInt || _isDouble || _isString) {
       argParser.addOption(argName,
           abbr: abbr,
@@ -1140,6 +1140,7 @@ class DartdocOptionContext {
   List<String> get includeExternal =>
       optionSet['includeExternal'].valueAt(context);
   bool get includeSource => optionSet['includeSource'].valueAt(context);
+  bool get injectHtml => optionSet['injectHtml'].valueAt(context);
   ToolConfiguration get tools => optionSet['tools'].valueAt(context);
 
   /// _input is only used to construct synthetic options.
@@ -1240,8 +1241,8 @@ Future<List<DartdocOption>> createDartdocOptions() async {
         mustExist: true),
     new DartdocOptionArgOnly<bool>('hideSdkText', false,
         hide: true,
-        help:
-            'Drop all text for SDK components.  Helpful for integration tests for dartdoc, probably not useful for anything else.',
+        help: 'Drop all text for SDK components.  Helpful for integration '
+            'tests for dartdoc, probably not useful for anything else.',
         negatable: true),
     new DartdocOptionArgFile<List<String>>('include', [],
         help: 'Library names to generate docs for.', splitCommas: true),
@@ -1254,6 +1255,9 @@ Future<List<DartdocOption>> createDartdocOptions() async {
         splitCommas: true),
     new DartdocOptionArgOnly<bool>('includeSource', true,
         help: 'Show source code blocks.', negatable: true),
+    new DartdocOptionArgOnly<bool>('injectHtml', false,
+        help: 'Allow the use of the {@inject-html} directive to inject raw '
+            'HTML into dartdoc output.'),
     new DartdocOptionArgOnly<String>('input', Directory.current.path,
         isDir: true, help: 'Path to source directory', mustExist: true),
     new DartdocOptionSyntheticOnly<String>('inputDir',
@@ -1323,7 +1327,7 @@ Future<List<DartdocOption>> createDartdocOptions() async {
             'A list of package names to place first when grouping libraries in packages. '
             'Unmentioned packages are sorted after these.'),
     new DartdocOptionArgOnly<bool>('sdkDocs', false,
-        help: 'Generate ONLY the docs for the Dart SDK.', negatable: false),
+        help: 'Generate ONLY the docs for the Dart SDK.'),
     new DartdocOptionArgSynth<String>('sdkDir',
         (DartdocSyntheticOption<String> option, Directory dir) {
       if (!option.parent['sdkDocs'].valueAt(dir) &&
@@ -1341,7 +1345,7 @@ Future<List<DartdocOption>> createDartdocOptions() async {
     new DartdocOptionArgFile<bool>('showUndocumentedCategories', false,
         help: "Label categories that aren't documented", negatable: true),
     new DartdocOptionArgOnly<bool>('showWarnings', false,
-        help: 'Display all warnings.', negatable: false),
+        help: 'Display all warnings.'),
     new DartdocOptionSyntheticOnly<PackageMeta>('topLevelPackageMeta',
         (DartdocSyntheticOption<PackageMeta> option, Directory dir) {
       PackageMeta packageMeta = new PackageMeta.fromDir(
@@ -1357,8 +1361,7 @@ Future<List<DartdocOption>> createDartdocOptions() async {
       return packageMeta;
     }, help: 'PackageMeta object for the default package.'),
     new DartdocOptionArgOnly<bool>('useCategories', true,
-        help: 'Display categories in the sidebar of packages',
-        negatable: false),
+        help: 'Display categories in the sidebar of packages'),
     new DartdocOptionArgOnly<bool>('validateLinks', true,
         help:
             'Runs the built-in link checker to display Dart context aware warnings for broken links (slow)',

lib/src/model.dart

@@ -4088,6 +4088,7 @@ abstract class ModelElement extends Canonicalization
   /// And the HTML fragment will not have been processed or changed by Markdown,
   /// but just injected verbatim.
   String _injectHtmlFragments(String rawDocs) {
+    if (!config.injectHtml) return rawDocs;
     final macroRegExp = new RegExp(r'<dartdoc-html>([a-f0-9]+)</dartdoc-html>');
     return rawDocs.replaceAllMapped(macroRegExp, (match) {
       String fragment = packageGraph.getHtmlFragment(match[1]);
@@ -4166,6 +4167,7 @@ abstract class ModelElement extends Canonicalization
   ///     &#123;@end-inject-html&#125;
   ///
   String _stripHtmlAndAddToIndex(String rawDocs) {
+    if (!config.injectHtml) return rawDocs;
     final templateRegExp = new RegExp(
         r'[ ]*{@inject-html\s*}([\s\S]+?){@end-inject-html}[ ]*\n?',
         multiLine: true);

test/model_test.dart

@@ -116,25 +116,62 @@ void main() {
     });
   });
 
-  group('HTML Injection', () {
+  group('HTML Injection when allowed', () {
     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);
+    PackageGraph injectionPackageGraph;
+    Library injectionExLibrary;
+
+    setUpAll(() async {
+      injectionPackageGraph = await utils.bootBasicPackage(
+          'testing/test_package', ['css', 'code_in_comments', 'excluded'],
+          additionalArguments: ['--inject-html']);
+
+      injectionExLibrary =
+          injectionPackageGraph.libraries.firstWhere((lib) => lib.name == 'ex');
+
+      htmlInjection = injectionExLibrary.classes
+          .firstWhere((c) => c.name == 'HtmlInjection');
+      injectSimpleHtml = htmlInjection.allInstanceMethods
+          .firstWhere((m) => m.name == 'injectSimpleHtml');
+      injectionPackageGraph.allLocalModelElements
+          .forEach((m) => m.documentation);
     });
+
     test("can inject HTML", () {
       expect(
           injectSimpleHtml.documentation,
-          contains('\n<dartdoc-html>bad2bbdd4a5cf9efb3212afff4449904756851aa</dartdoc-html>\n'));
+          contains(
+              '\n<dartdoc-html>bad2bbdd4a5cf9efb3212afff4449904756851aa</dartdoc-html>\n'));
+      expect(injectSimpleHtml.documentation,
+          isNot(contains('\n{@inject-html}\n')));
       expect(injectSimpleHtml.documentationAsHtml,
           contains('   <div style="opacity: 0.5;">[HtmlInjection]</div>'));
     });
   });
 
+  group('HTML Injection when not allowed', () {
+    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("doesn't inject HTML if --inject-html option is not present", () {
+      expect(
+          injectSimpleHtml.documentation,
+          isNot(contains(
+              '\n<dartdoc-html>bad2bbdd4a5cf9efb3212afff4449904756851aa</dartdoc-html>\n')));
+      expect(injectSimpleHtml.documentation, isNot(contains('<dartdoc-html>')));
+      expect(injectSimpleHtml.documentationAsHtml, contains('{@inject-html}'));
+    });
+  });
+
   group('Missing and Remote', () {
     test('Verify that SDK libraries are not canonical when missing', () {
       expect(
@@ -1995,8 +2032,9 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
           reason: "Can't find convertToMap function in ${fakePath}");
       if (Platform.isWindows) fakePath = fakePath.replaceAll('/', r'\\');
 
-      crossdartPackageGraph = await utils
-          .bootBasicPackage(utils.testPackageDir.path, [], withCrossdart: true);
+      crossdartPackageGraph = await utils.bootBasicPackage(
+          utils.testPackageDir.path, [],
+          additionalArguments: ['--add-crossdart']);
       crossdartFakeLibrary =
           crossdartPackageGraph.libraries.firstWhere((l) => l.name == 'fake');
       HasGenerics = crossdartFakeLibrary.classes

test/src/utils.dart

@@ -60,18 +60,22 @@ void delete(Directory dir) {
   if (dir.existsSync()) dir.deleteSync(recursive: true);
 }
 
-void init() async {
+void init({List<String> additionalArguments}) async {
   sdkDir = defaultSdkDir;
   sdkPackageMeta = new PackageMeta.fromDir(sdkDir);
+  additionalArguments ??= <String>[];
 
   testPackageGraph = await bootBasicPackage(
-      'testing/test_package', ['css', 'code_in_comments', 'excluded']);
+      'testing/test_package', ['css', 'code_in_comments', 'excluded'],
+      additionalArguments: additionalArguments);
   testPackageGraphGinormous = await bootBasicPackage(
       'testing/test_package', ['css', 'code_in_commnets', 'excluded'],
-      withAutoIncludedDependencies: true);
+      additionalArguments:
+          additionalArguments + ['--auto-include-dependencies']);
 
-  testPackageGraphSmall =
-      await bootBasicPackage('testing/test_package_small', []);
+  testPackageGraphSmall = await bootBasicPackage(
+      'testing/test_package_small', [],
+      additionalArguments: additionalArguments);
   testPackageGraphSdk = await bootSdkPackage();
 }
 
@@ -82,18 +86,17 @@ Future<PackageGraph> bootSdkPackage() async {
 
 Future<PackageGraph> bootBasicPackage(
     String dirPath, List<String> excludeLibraries,
-    {bool withAutoIncludedDependencies = false,
-    bool withCrossdart = false}) async {
+    {List<String> additionalArguments}) async {
   Directory dir = new Directory(dirPath);
+  additionalArguments ??= <String>[];
   return new PackageBuilder(await contextFromArgv([
-    '--input',
-    dir.path,
-    '--sdk-dir',
-    sdkDir.path,
-    '--exclude',
-    excludeLibraries.join(','),
-    '--${withCrossdart ? "" : "no-"}add-crossdart',
-    '--${withAutoIncludedDependencies ? "" : "no-"}auto-include-dependencies'
-  ]))
+            '--input',
+            dir.path,
+            '--sdk-dir',
+            sdkDir.path,
+            '--exclude',
+            excludeLibraries.join(','),
+          ] +
+          additionalArguments))
       .buildPackageGraph();
 }