cargdev/angular
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(aio): support annotating JSON files with doc-regions

Browse Source 
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"}
```
This commit is contained in:
Peter Bacon Darwin
2017-02-21 13:09:57 +00:00
committed by Igor Minar
parent bee567afad
commit 3f8d5ac478
3 changed files with 23 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
aio/transforms/examples-package/processors/collect-examples.js
View File

@ -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));