Skip to content
This repository was archived by the owner on Dec 4, 2017. It is now read-only.

Fix decorator docs #2349

Closed
petebacondarwin wants to merge 2 commits into from
Closed

Fix decorator docs #2349

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8871ea2
revert: fix: merge the decorator data with the symbol
petebacondarwin Sep 14, 2016
944b8d7
fix(api-builder): correctly render decorator docs
petebacondarwin Sep 14, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
179 changes: 72 additions & 107 deletions tools/api-builder/angular.io-package/processors/addJadeDataDocsProcessor.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,65 +19,6 @@ var titleCase = function(text) {
*
*/


function processExportDoc(exportDoc) {
// STABILITY STATUS
// Supported tags:
// @stable
// @experimental
// @deprecated
// Default is the empty string (no badge)
// Do not capitalize the strings, they are intended for use in constructing a css class from _hero.scss
// and used in _hero.jade
var stability = '';
if (_.has(exportDoc, 'stable')) {
stability = 'stable';
} else if (_.has(exportDoc, 'experimental')) {
stability = 'experimental';
} else if (_.has(exportDoc, 'deprecated')) {
stability = 'deprecated';
exportDoc.showDeprecatedNotes = true;
}

var howToUse = '';
if(_.has(exportDoc, 'howToUse')) {
var howToUseArray = exportDoc.tags.tags.filter(function(tag) {
return tag.tagName === 'howToUse'
});

// Remove line breaks, there should only be one tag
howToUse = howToUseArray[0].description.replace(/(\r\n|\n|\r)/gm," ");
}

var whatItDoes = '';
if(_.has(exportDoc, 'whatItDoes')) {
var whatItDoesArray = exportDoc.tags.tags.filter(function(tag) {
return tag.tagName === 'whatItDoes'
});

// Remove line breaks, there should only be one tag
whatItDoes = whatItDoesArray[0].description.replace(/(\r\n|\n|\r)/gm," ");
}

// SECURITY STATUS
// Supported tags:
// @security
// Default is no security risk assessed for api
var security = false;
if (_.has(exportDoc, 'security')) {
var securityArray = exportDoc.tags.tags.filter(function(tag) {
return tag.tagName === 'security'
});

// Remove line breaks, there should only be one tag
security = securityArray[0].description.replace(/(\r\n|\n|\r)/gm," ");

exportDoc.showSecurityNotes = true;
}

return {stability: stability, howToUse: howToUse, whatItDoes: whatItDoes, security: security};
}

module.exports = function addJadeDataDocsProcessor() {
return {
$runAfter: ['adding-extra-docs'],
Expand Down Expand Up @@ -110,7 +51,7 @@ module.exports = function addJadeDataDocsProcessor() {
*
* Modules must be public and have content
*/

_.forEach(docs, function(doc) {
if (doc.docType === 'module' && !doc.internal && doc.exports.length) {
modules.push(doc);
Expand All @@ -124,60 +65,83 @@ module.exports = function addJadeDataDocsProcessor() {
intro: doc.description.replace('"', '\"').replace(/\s*(\r?\n|\r)\s*/g," "),
docType: 'module'
}];

var decorators = {};


// GET DATA FOR EACH PAGE (CLASS, VARS, FUNCTIONS)
var modulePageInfo = _(doc.exports)
.map(function(exportDoc) {
// if it ends with "Decorator", we store it in the map
// to later merge with the token
if (exportDoc.name.endsWith("Decorator")) {
var p = processExportDoc(exportDoc.callMember);
decorators[exportDoc.name] = {
stability : p.stability,
howToUse : p.howToUse,
whatItDoes : p.whatItDoes,
security : p.security,
description : exportDoc.callMember.description,
docType: 'decorator'
};
return null;

} else {
var p = processExportDoc(exportDoc);

// Data inserted into jade-data.template.html
var dataDoc = {
name: exportDoc.name + '-' + exportDoc.docType,
title: exportDoc.name,
docType: exportDoc.docType,
exportDoc: exportDoc,
stability: p.stability,
howToUse: p.howToUse,
whatItDoes: p.whatItDoes,
security: p.security
};

if (exportDoc.symbolTypeName) dataDoc.varType = titleCase(exportDoc.symbolTypeName);
if (exportDoc.originalModule) dataDoc.originalModule = exportDoc.originalModule;

return dataDoc;

// STABILITY STATUS
// Supported tags:
// @stable
// @experimental
// @deprecated
// Default is the empty string (no badge)
// Do not capitalize the strings, they are intended for use in constructing a css class from _hero.scss
// and used in _hero.jade
var stability = '';
if (_.has(exportDoc, 'stable')) {
stability = 'stable';
} else if (_.has(exportDoc, 'experimental')) {
stability = 'experimental';
} else if (_.has(exportDoc, 'deprecated')) {
stability = 'deprecated';
exportDoc.showDeprecatedNotes = true;
}

var howToUse = '';
if(_.has(exportDoc, 'howToUse')) {
var howToUseArray = exportDoc.tags.tags.filter(function(tag) {
return tag.tagName === 'howToUse'
});

// Remove line breaks, there should only be one tag
howToUse = howToUseArray[0].description.replace(/(\r\n|\n|\r)/gm," ");
}

var whatItDoes = '';
if(_.has(exportDoc, 'whatItDoes')) {
var whatItDoesArray = exportDoc.tags.tags.filter(function(tag) {
return tag.tagName === 'whatItDoes'
});

// Remove line breaks, there should only be one tag
whatItDoes = whatItDoesArray[0].description.replace(/(\r\n|\n|\r)/gm," ");
}

// SECURITY STATUS
// Supported tags:
// @security
// Default is no security risk assessed for api
var security = false;
if (_.has(exportDoc, 'security')) {
var securityArray = exportDoc.tags.tags.filter(function(tag) {
return tag.tagName === 'security'
});

// Remove line breaks, there should only be one tag
security = securityArray[0].description.replace(/(\r\n|\n|\r)/gm," ");

exportDoc.showSecurityNotes = true;
}

// Data inserted into jade-data.template.html
var dataDoc = {
name: exportDoc.name + '-' + exportDoc.docType,
title: exportDoc.name,
docType: exportDoc.docType,
exportDoc: exportDoc,
stability: stability,
howToUse: howToUse,
whatItDoes: whatItDoes,
security: security
};

if (exportDoc.symbolTypeName) dataDoc.varType = titleCase(exportDoc.symbolTypeName);
if (exportDoc.originalModule) dataDoc.originalModule = exportDoc.originalModule;
return dataDoc;
})
.filter(function(s) { return !!s; }) // filter out all null values
.sortBy('name')
.value();

// find a matching symbol for every decorator item
// and merge the data
_.forEach(Object.keys(decorators), function(name) {
var varToken = name.split("Decorator")[0];
var c = modulePageInfo.filter(function(n) { return n.exportDoc.name === varToken; });

c[0].docType = decorators[name].docType;
Object.assign(c[0].exportDoc, decorators[name]);
});

doc.childPages = modulePageInfo;

Expand All @@ -198,6 +162,7 @@ module.exports = function addJadeDataDocsProcessor() {
}
});


return docs.concat(extraDocs);
}
};
Expand Down
4 changes: 2 additions & 2 deletions tools/api-builder/angular.io-package/templates/decorator.template.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,12 @@
{$ doc.description | indentForMarkdown(6) | trimBlankLines $}
{% endif %}

{% if doc.metadataDoc and doc.metadataDoc.members.length %}
{% if doc.members.length %}
div(layout="row" layout-xs="column" class="metadata" class="row-margin ng-cloak")
div(flex="20" flex-xs="100")
h2(class="h2-api-docs") Metadata Properties
div(class="code-links" flex="80" flex-xs="100")
{% for metadata in doc.metadataDoc.members %}{% if not metadata.internal %}
{% for metadata in doc.members %}{% if not metadata.internal %}
a(name="{$ metadata.name $}-anchor" class="anchor-offset")
pre(class="prettyprint no-bg" ng-class="{ 'anchor-focused': appCtrl.isApiDocMemberFocused('{$ metadata.name $}') }")
code(class="api-doc-code").
Expand Down
2 changes: 1 addition & 1 deletion tools/api-builder/docs-package/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ module.exports = new Package('angular-v2-docs', [jsdocPackage, nunjucksPackage,
.processor(require('./processors/checkUnbalancedBackTicks'))
.processor(require('./processors/convertBackticksToCodeBlocks'))
.processor(require('./processors/addNotYetDocumentedProperty'))
.processor(require('./processors/mergeDecoratorDocsEmpty'))
.processor(require('./processors/mergeDecoratorDocs'))
.processor(require('./processors/extractDecoratedClasses'))

.config(function(parseTagsProcessor) {
Expand Down
57 changes: 24 additions & 33 deletions tools/api-builder/docs-package/processors/mergeDecoratorDocs.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,54 +1,45 @@
var _ = require('lodash');

module.exports = function mergeDecoratorDocs() {
module.exports = function mergeDecoratorDocs(log) {
return {
$runAfter: ['processing-docs'],
$runBefore: ['docs-processed'],
docsToMergeInfo: [
{ nameTemplate: _.template('${name}Decorator'), decoratorProperty: 'decoratorInterfaceDoc' },
{ nameTemplate: _.template('${name}Metadata'), decoratorProperty: 'metadataDoc', useFields: ['howToUse', 'whatItDoes'] },
{ nameTemplate: _.template('${name}MetadataType'), decoratorProperty: 'metadataInterfaceDoc' },
{ nameTemplate: _.template('${name}MetadataFactory'), decoratorProperty: 'metadataFactoryDoc' }
makeDecoratorCalls: [
{ type: '', description: 'toplevel'},
{ type: 'Prop', description: 'property'},
{ type: 'Param', description: 'parameter'},
],
$process: function(docs) {

var docsToMergeInfo = this.docsToMergeInfo;
var makeDecoratorCalls = this.makeDecoratorCalls;
var docsToMerge = Object.create(null);

docs.forEach(function(doc) {

// find all the decorators, signified by a call to `makeDecorator(metadata)`
var makeDecorator = getMakeDecoratorCall(doc);
if (makeDecorator) {
doc.docType = 'decorator';
// get the type of the decorator metadata
doc.decoratorType = makeDecorator.arguments[0].text;
// clear the symbol type named (e.g. ComponentMetadataFactory) since it is not needed
doc.symbolTypeName = undefined;
makeDecoratorCalls.forEach(function(call) {
// find all the decorators, signified by a call to `makeDecorator(metadata)`
var makeDecorator = getMakeDecoratorCall(doc, call.type);
if (makeDecorator) {
log.debug('mergeDecoratorDocs: found decorator', doc.docType, doc.name);
doc.docType = 'decorator';
doc.decoratorLocation = call.description;
// get the type of the decorator metadata
doc.decoratorType = makeDecorator.arguments[0].text;
// clear the symbol type named (e.g. ComponentMetadataFactory) since it is not needed
doc.symbolTypeName = undefined;

// keep track of the docs that need to be merged into this decorator doc
docsToMergeInfo.forEach(function(info) {
docsToMerge[info.nameTemplate({name: doc.name})] = { decoratorDoc: doc, property: info.decoratorProperty };
});
}
// keep track of the names of the docs that need to be merged into this decorator doc
docsToMerge[doc.name + 'Decorator'] = doc;
}
});
});

// merge the metadata docs into the decorator docs
docs = docs.filter(function(doc) {
if (docsToMerge[doc.name]) {
var decoratorDoc = docsToMerge[doc.name].decoratorDoc;
var property = docsToMerge[doc.name].property;
var useFields = docsToMerge[doc.name].useFields;

// attach this document to its decorator
decoratorDoc[property] = doc;

// Copy over fields from the merged doc if specified
if (useFields) {
useFields.forEach(function(field) {
decoratorDoc[field] = doc[field];
});
}
var decoratorDoc = docsToMerge[doc.name];
log.debug('mergeDecoratorDocs: merging', doc.name, 'into', decoratorDoc.name, doc.callMember.description.substring(0, 50));
decoratorDoc.description = doc.callMember.description;

// remove doc from its module doc's exports
doc.moduleDoc.exports = doc.moduleDoc.exports.filter(function(exportDoc) { return exportDoc !== doc; });
Expand Down
10 changes: 5 additions & 5 deletions tools/api-builder/docs-package/processors/mergeDecoratorDocs.spec.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ var mockPackage = require('../mocks/mockPackage');
var Dgeni = require('dgeni');

describe('mergeDecoratorDocs processor', function() {
var dgeni, injector, processor, decoratorDoc, otherDoc;
var dgeni, injector, processor, decoratorDoc, decoratorDocWithTypeAssertion, otherDoc;

beforeEach(function() {
dgeni = new Dgeni([mockPackage()]);
Expand All @@ -16,7 +16,7 @@ describe('mergeDecoratorDocs processor', function() {
valueDeclaration: {
initializer: {
expression: { text: 'makeDecorator' },
arguments: [{ text: 'XMetadata' }]
arguments: [{ text: 'X' }]
}
}
}
Expand All @@ -31,7 +31,7 @@ describe('mergeDecoratorDocs processor', function() {
expression: {
type: {},
expression: { text: 'makeDecorator' },
arguments: [{ text: 'YMetadata' }]
arguments: [{ text: 'Y' }]
}
}
}
Expand Down Expand Up @@ -61,7 +61,7 @@ describe('mergeDecoratorDocs processor', function() {

it('should extract the "type" of the decorator meta data', function() {
processor.$process([decoratorDoc, decoratorDocWithTypeAssertion, otherDoc]);
expect(decoratorDoc.decoratorType).toEqual('XMetadata');
expect(decoratorDocWithTypeAssertion.decoratorType).toEqual('YMetadata');
expect(decoratorDoc.decoratorType).toEqual('X');
expect(decoratorDocWithTypeAssertion.decoratorType).toEqual('Y');
});
});
10 changes: 0 additions & 10 deletions tools/api-builder/docs-package/processors/mergeDecoratorDocsEmpty.js
View file
Open in desktop

This file was deleted.