From 3f8d5ac478e3ef2ef36c1b6fc883160c83fbf17b Mon Sep 17 00:00:00 2001
From: Peter Bacon Darwin <pete@bacondarwin.com>
Date: Tue, 21 Feb 2017 13:09:57 +0000
Subject: [PATCH] feat(aio): support annotating JSON files with doc-regions

This change allows the example writer to add doc-region annotations to
files that do not allow comments. This is done by creating a clone of the
file and adding `.annotated` to the file name. This new file can contain
inline `// ...` comments that can be used to annotate the doc regions.

Example:

**package.json**

```
{
  "name": "angular.io",
  "version": "0.0.0",
  "main": "index.js",
  "repository": "git@github.com:angular/angular.git",
  "author": "Angular",
  "license": "MIT",
  "private": true,
}
````

**package.json.annotated**

```
{
  "name": "angular.io",
// #docregion version
  "version": "0.0.0",
// #enddocregion
  "main": "index.js",
  "repository": "git@github.com:angular/angular.git",
  "author": "Angular",
  "license": "MIT",
  "private": true,
}
````

This region can then be referenced in examples just like any other doc region:

```
{@example 'package.json' region="version"}
```
---
 .../examples-package/inline-tag-defs/example.js   | 15 ++++++++++-----
 .../processors/collect-examples.js                | 12 +++++++++++-
 .../examples-package/services/region-parser.js    |  3 ++-
 3 files changed, 23 insertions(+), 7 deletions(-)

diff --git a/aio/transforms/examples-package/inline-tag-defs/example.js b/aio/transforms/examples-package/inline-tag-defs/example.js
index 162d67afaa..309a0a01fb 100644
--- a/aio/transforms/examples-package/inline-tag-defs/example.js
+++ b/aio/transforms/examples-package/inline-tag-defs/example.js
@@ -33,16 +33,21 @@ module.exports = function exampleInlineTagDef(
 
       // Find the example in the folders
       var exampleFile;
+      // Try an "annotated" version first
       EXAMPLES_FOLDERS.some(
-          EXAMPLES_FOLDER => { return exampleFile = exampleMap[EXAMPLES_FOLDER][relativePath]; });
+          EXAMPLES_FOLDER => { return exampleFile = exampleMap[EXAMPLES_FOLDER][relativePath + '.annotated']; });
 
+      // If no annotated version is available then try the actual file
+      if (!exampleFile) {
+        EXAMPLES_FOLDERS.some(
+            EXAMPLES_FOLDER => { return exampleFile = exampleMap[EXAMPLES_FOLDER][relativePath]; });
+      }
+
+      // If still no file then we error
       if (!exampleFile) {
         log.error(
             createDocMessage('Missing example file... relativePath: "' + relativePath + '".', doc));
-        log.error(
-            'Example files available are:',
-            EXAMPLES_FOLDERS.map(
-                EXAMPLES_FOLDER => Object.keys(exampleMap[EXAMPLES_FOLDER]).join('\n')));
+        log.error('Example files can be found in: ' + EXAMPLES_FOLDERS.join(', '));
         return '';
       }
 
diff --git a/aio/transforms/examples-package/processors/collect-examples.js b/aio/transforms/examples-package/processors/collect-examples.js
index d883b772f9..069f60b264 100644
--- a/aio/transforms/examples-package/processors/collect-examples.js
+++ b/aio/transforms/examples-package/processors/collect-examples.js
@@ -1,3 +1,4 @@
+const {extname} = require('canonical-path');
 const {mapObject} = require('../utils');
 
 module.exports = function collectExamples(exampleMap, regionParser, log, createDocMessage) {
@@ -19,7 +20,16 @@ module.exports = function collectExamples(exampleMap, regionParser, log, createD
                 exampleMap[folder] = exampleMap[folder] || {};
                 exampleMap[folder][relativePath] = doc;
 
-                const parsedRegions = regionParser(doc.content, doc.fileInfo.extension);
+                // We treat files that end in `.annotated` specially
+                // They are used to annotate files that cannot contain comments, such as JSON
+                // So you provide two files: `xyz.json` and `xyz.json.annotated`, which is a copy
+                // of the original but contains inline doc region comments
+                let fileType = doc.fileInfo.extension;
+                if (fileType === 'annotated') {
+                  fileType = extname(doc.fileInfo.baseName).substr(1) + '.' + fileType;
+                }
+
+                const parsedRegions = regionParser(doc.content, fileType);
 
                 log.debug(
                     'found example file', folder, relativePath, Object.keys(parsedRegions.regions));
diff --git a/aio/transforms/examples-package/services/region-parser.js b/aio/transforms/examples-package/services/region-parser.js
index 49a579af3d..90efabb854 100644
--- a/aio/transforms/examples-package/services/region-parser.js
+++ b/aio/transforms/examples-package/services/region-parser.js
@@ -19,7 +19,8 @@ regionParserImpl.regionMatchers = {
   html: html,
   css: blockC,
   yaml: inlineHash,
-  jade: inlineCOnly
+  jade: inlineCOnly,
+  'json.annotated': inlineC
 };
 
 /**