feat: support @example insertion of .md file fragments (#1295)

* Fix link in CONTRIBUTING.md

* feat: support @example insertion of .md file fragments

Fixes #1105

Author: chalin

CONTRIBUTING.md

@@ -23,7 +23,7 @@ yet in the issue tracker, start by opening an issue. Thanks!
 
 1. `grind` is needed to run dartdoc integration tests, see installed via `pub global activate grinder`.
 2. When a change is user-facing, please add a new entry to the [changelog](https://github.com/dart-lang/dartdoc/blob/master/CHANGELOG.md)
-3. Please include a test for your change.  `dartdoc` has both `package:test`-style unittests as well as integration tests.  To run the unittests, use `dart test/all.dart`.  Most changes can be tested via a unittest, but some require modifying the (test_package)[https://github.com/dart-lang/dartdoc/tree/master/testing/test_package] and regenerating its docs via `grind update-test-package-docs`.
+3. Please include a test for your change.  `dartdoc` has both `package:test`-style unittests as well as integration tests.  To run the unittests, use `dart test/all.dart`.  Most changes can be tested via a unittest, but some require modifying the [test_package](https://github.com/dart-lang/dartdoc/tree/master/testing/test_package) and regenerating its docs via `grind update-test-package-docs`.
 4.  Be sure to format your Dart code using `dartfmt -w`, otherwise travis will complain.
 5.  Post your change via a pull request for review and integration!
 

lib/src/model.dart

@@ -1716,32 +1716,82 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
     return lib;
   }
 
-  // process the {@example ...} in comments and inject the example
-  // code into the doc commment.
-  // {@example core/ts/bootstrap/bootstrap.ts region='bootstrap'}
+  /// Replace {@example ...} in API comments with the content of named file.
+  ///
+  /// Syntax:
+  ///
+  ///     {@example PATH [region=NAME] [lang=NAME]}
+  ///
+  /// where PATH and NAME are tokens _without_ whitespace; NAME can optionally be
+  /// quoted (use of quotes is for backwards compatibility and discouraged).
+  ///
+  /// If PATH is `dir/file.ext` and region is `r` then we'll look for the file
+  /// named `dir/file-r.ext.md`, relative to the project root directory (of the
+  /// project for which the docs are being generated).
+  ///
+  /// Examples:
+  ///
+  ///     {@example examples/angular/quickstart/web/main.dart}
+  ///     {@example abc/def/xyz_component.dart region=template lang=html}
+  ///
   String _injectExamples(String rawdocs) {
-    if (rawdocs.contains('@example')) {
-      RegExp exp = new RegExp(r"{@example .+}");
-      Iterable<Match> matches = exp.allMatches(rawdocs);
-      var dirPath = this.package.packageMeta.dir.path;
-      for (var match in matches) {
-        var strings = match.group(0).split(' ');
-        var path = strings[1].replaceAll('/', Platform.pathSeparator);
-        if (path.contains(Platform.pathSeparator) &&
-            !path.startsWith(Platform.pathSeparator)) {
-          var file = new File(p.join(dirPath, 'examples', path));
-          if (file.existsSync()) {
-            // TODO(keertip):inject example
-          } else {
-            var filepath =
-                this.element.source.fullName.substring(dirPath.length + 1);
-            stdout.write(
-                '\nwarning: ${filepath}: file ${strings[1]} does not exist.');
-          }
+    final dirPath = this.package.packageMeta.dir.path;
+    RegExp exampleRE = new RegExp(r'{@example\s+([^}]+)}');
+    return rawdocs.replaceAllMapped(exampleRE, (match) {
+      var args = _getExampleArgs(match[1]);
+      var lang = args['lang'] ?? p.extension(args['src']);
+
+      var replacement = match[0]; // default to fully matched string.
+
+      var fragmentFile = new File(p.join(dirPath, args['file']));
+      if (fragmentFile.existsSync()) {
+        replacement = fragmentFile.readAsStringSync();
+        if (!lang.isEmpty) {
+          replacement = replacement.replaceFirst('```', '```$lang');
         }
+      } else {
+        // TODO: is this the proper way to handle warnings?
+        var filePath = this.element.source.fullName.substring(dirPath.length + 1);
+        final msg = 'Warning: ${filePath}: @example file not found, $fragmentFile';
+        stderr.write(msg);
       }
-    }
-    return rawdocs;
+      return replacement;
+    });
+  }
+
+  /// 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
+  /// 'file'.
+  Map<String, String> _getExampleArgs(String argsAsString) {
+    // Extract PATH and return is under key 'src'
+    var endOfSrc = argsAsString.indexOf(' ');
+    if (endOfSrc < 0) endOfSrc = argsAsString.length;
+    var src = argsAsString.substring(0, endOfSrc);
+    src = src.replaceAll('/', Platform.pathSeparator);
+    final args = { 'src': src };
+
+    // Process remaining named arguments
+    var namedArgs = argsAsString.substring(endOfSrc);
+    // Arg value: allow optional quotes; warning: we still don't support whitespace.
+    RegExp keyValueRE = new RegExp('(\\w+)=[\'"]?(\\S*)[\'"]?');
+    Iterable<Match> matches = keyValueRE.allMatches(namedArgs);
+    matches.forEach((match) {
+      args[match[1]] = match[2];
+    });
+
+    // Compute 'file'
+    final fragExtension = '.md';
+    var file = src + fragExtension;
+    var region = args['region'] ?? '';
+    if (!region.isEmpty) {
+      var dir = p.dirname(src);
+      var basename = p.basenameWithoutExtension(src);
+      var ext = p.extension(src);
+      file = p.join(dir, '$basename-$region$ext$fragExtension');
+    }
+    args['file'] = file;
+    return args;
   }
 }
 

test/compare_output_test.dart

@@ -133,9 +133,9 @@ void main() {
         fail('dartdoc failed');
       }
 
-      if (!result.stdout
-          .contains('core/pipes/ts/slice_pipe/slice_pipe_example.ts')) {
-        fail('Did not process @example in comments');
+      if (!result.stderr
+          .contains(new RegExp(r'Warning:.*file-does-not-exist\.js'))) {
+        fail('Warning missing for nonexistent @example: \nstdout: ${result.stdout} \nstderr: ${result.stderr}');
       }
     });
 

testing/test_package/examples/dog_food-meat.txt.md

@@ -0,0 +1,4 @@
+A selection of dog flavors:
+
+- beef
+- poultry

testing/test_package/examples/dog_food.md

@@ -0,0 +1 @@
+Some text with **bold** remarks.

testing/test_package/examples/test.dart.md

@@ -0,0 +1,3 @@
+```
+<h1>Hello <b>World</b>!</h1>
+```

testing/test_package/lib/example.dart

@@ -194,7 +194,12 @@ class ConstantCat implements Cat {
 }
 
 /// implements [Cat], [E]
-/// {@example core/pipes/ts/slice_pipe/slice_pipe_example.ts region='SlicePipe_list'}
+///
+/// {@example examples/dog_food}
+/// {@example examples/dog_food.txt region=meat}
+///
+/// {@example examples/test.dart region= lang=html}
+/// {@example examples/file-does-not-exist.js}
 class Dog implements Cat, E {
   String name;
 

testing/test_package_docs/ex/Dog-class.html

@@ -136,8 +136,12 @@ <h5><a href="ex/ex-library.html">ex</a></h5>
   <div class="col-xs-12 col-sm-9 col-md-8 main-content">
 
     <section class="desc markdown">
-      <p>implements <a href="ex/Cat-class.html">Cat</a>, <a href="ex/E-class.html">E</a>
-{@example core/pipes/ts/slice_pipe/slice_pipe_example.ts region='SlicePipe_list'}</p>
+      <p>implements <a href="ex/Cat-class.html">Cat</a>, <a href="ex/E-class.html">E</a></p>
+<p>Some text with <strong>bold</strong> remarks.
+A selection of dog flavors:</p><ul><li>beef</li><li>poultry</li></ul>
+<pre class="language-html prettyprint"><code class="language-html">&lt;h1&gt;Hello &lt;b&gt;World&lt;/b&gt;!&lt;/h1&gt;
+</code></pre>
+<p>{@example examples/file-does-not-exist.js}</p>
     </section>
 
     <section>

testing/test_package_docs/ex/ex-library.html

@@ -350,8 +350,7 @@ <h2>Classes</h2>
           <span class="name "><a href="ex/Dog-class.html">Dog</a></span>
         </dt>
         <dd>
-          <p>implements <a href="ex/Cat-class.html">Cat</a>, <a href="ex/E-class.html">E</a>
-{@example core/pipes/ts/slice_pipe/slice_pipe_example.ts region='SlicePipe_list'}</p>
+          <p>implements <a href="ex/Cat-class.html">Cat</a>, <a href="ex/E-class.html">E</a></p>
         </dd>
         <dt id="E">
           <span class="name "><a href="ex/E-class.html">E</a></span>