Don't HTML escape source code blocks in Markdown (#2253)

* Don't HTML escape source code blocks in Markdown

Adds a renderer in between to control whether or not we apply HTML
escapes to source code blocks.

Fixes #2252

Author: jdkoren

lib/src/model/model_element.dart

@@ -26,6 +26,7 @@ import 'package:dartdoc/src/model/model.dart';
 import 'package:dartdoc/src/model_utils.dart' as utils;
 import 'package:dartdoc/src/render/model_element_renderer.dart';
 import 'package:dartdoc/src/render/parameter_renderer.dart';
+import 'package:dartdoc/src/render/source_code_renderer.dart';
 import 'package:dartdoc/src/source_linker.dart';
 import 'package:dartdoc/src/tuple.dart';
 import 'package:dartdoc/src/utils.dart';
@@ -930,6 +931,9 @@ abstract class ModelElement extends Canonicalization
   ParameterRenderer get _parameterRendererDetailed =>
       packageGraph.rendererFactory.parameterRendererDetailed;
 
+  SourceCodeRenderer get _sourceCodeRenderer =>
+      packageGraph.rendererFactory.sourceCodeRenderer;
+
   String get linkedParams => _parameterRenderer.renderLinkedParams(parameters);
 
   String get linkedParamsLines =>
@@ -1091,6 +1095,14 @@ abstract class ModelElement extends Canonicalization
     return __documentation;
   }
 
+  String _sourceCode;
+
+  @override
+  String get sourceCode {
+    return _sourceCode ??=
+        _sourceCodeRenderer.renderSourceCode(super.sourceCode);
+  }
+
   bool canOverride() =>
       element is ClassMemberElement || element is PropertyAccessorElement;
 

lib/src/model/model_node.dart

@@ -2,8 +2,6 @@
 // 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.
 
-import 'dart:convert';
-
 import 'package:analyzer/dart/ast/ast.dart';
 import 'package:analyzer/dart/element/element.dart';
 import 'package:dartdoc/src/model_utils.dart' as model_utils;
@@ -63,7 +61,6 @@ class ModelNode {
         var start = _sourceOffset - (_sourceOffset - i);
         var source = contents.substring(start, _sourceEnd);
 
-        source = const HtmlEscape().convert(source);
         source = model_utils.stripIndentFromSource(source);
         source = model_utils.stripDartdocCommentsFromSource(source);
 

lib/src/render/renderer_factory.dart

@@ -10,6 +10,7 @@ import 'package:dartdoc/src/render/enum_field_renderer.dart';
 import 'package:dartdoc/src/render/feature_renderer.dart';
 import 'package:dartdoc/src/render/model_element_renderer.dart';
 import 'package:dartdoc/src/render/parameter_renderer.dart';
+import 'package:dartdoc/src/render/source_code_renderer.dart';
 import 'package:dartdoc/src/render/template_renderer.dart';
 import 'package:dartdoc/src/render/type_parameters_renderer.dart';
 import 'package:dartdoc/src/render/typedef_renderer.dart';
@@ -50,6 +51,8 @@ abstract class RendererFactory {
 
   ParameterRenderer get parameterRendererDetailed;
 
+  SourceCodeRenderer get sourceCodeRenderer;
+
   TypeParametersRenderer get typeParametersRenderer;
 
   TypedefRenderer get typedefRenderer;
@@ -102,6 +105,9 @@ class HtmlRenderFactory extends RendererFactory {
 
   @override
   FeatureRenderer get featureRenderer => FeatureRendererHtml();
+
+  @override
+  SourceCodeRenderer get sourceCodeRenderer => SourceCodeRendererHtml();
 }
 
 class MdRenderFactory extends RendererFactory {
@@ -152,4 +158,7 @@ class MdRenderFactory extends RendererFactory {
 
   @override
   FeatureRenderer get featureRenderer => FeatureRendererMd();
+
+  @override
+  SourceCodeRenderer get sourceCodeRenderer => SourceCodeRendererNoop();
 }

lib/src/render/source_code_renderer.dart

@@ -0,0 +1,23 @@
+// 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.
+
+import 'dart:convert';
+
+/// Renderer for source code snippets extracted from source files.
+abstract class SourceCodeRenderer {
+  String renderSourceCode(String source);
+}
+
+class SourceCodeRendererNoop extends SourceCodeRenderer {
+  @override
+  String renderSourceCode(String source) => source;
+}
+
+/// [SourceCodeRenderer] that escapes characters for HTML.
+class SourceCodeRendererHtml extends SourceCodeRenderer {
+  @override
+  String renderSourceCode(String source) {
+    return (const HtmlEscape()).convert(source);
+  }
+}

tool/grind.dart

@@ -555,16 +555,34 @@ Future<void> serveTestExperimentsPackageDocs() async {
       'test-package-docs-experiments');
 }
 
-@Task('Build generated test package docs (with inherited docs and source code)')
+@Task('Build test package docs (HTML) with inherited docs and source code')
 @Depends(clean)
 Future<void> buildTestPackageDocs() async {
   await _buildTestPackageDocs(
       testPackageDocsDir.absolute.path, Directory.current.path);
 }
 
+@Task('Build test package docs (Markdown) with inherited docs and source code')
+@Depends(clean)
+Future<void> buildTestPackageDocsMd() async {
+  await _buildTestPackageDocs(
+      testPackageDocsDir.absolute.path, Directory.current.path,
+      params: ['--format', 'md']);
+}
+
 @Task('Serve test package docs locally with dhttpd on port 8002')
 @Depends(buildTestPackageDocs)
 Future<void> serveTestPackageDocs() async {
+  await startTestPackageDocsServer();
+}
+
+@Task('Serve test package docs (in Markdown) locally with dhttpd on port 8002')
+@Depends(buildTestPackageDocsMd)
+Future<void> serveTestPackageDocsMd() async {
+  await startTestPackageDocsServer();
+}
+
+Future<void> startTestPackageDocsServer() async {
   log('launching dhttpd on port 8002 for SDK');
   var launcher = SubprocessLauncher('serve-test-package-docs');
   await launcher.runStreamed(sdkBin('pub'), [