486 lines
14 KiB
JavaScript
486 lines
14 KiB
JavaScript
/**
|
|
* @license
|
|
* Copyright (c) 2015 The Polymer Project Authors. All rights reserved.
|
|
* This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
|
|
* The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
|
|
* The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
|
|
* Code distributed by Google as part of the polymer project is also
|
|
* subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
|
|
*/
|
|
'use strict';
|
|
|
|
// jshint node:true
|
|
|
|
var jsdoc = require('./jsdoc');
|
|
|
|
var dom5 = require('dom5');
|
|
|
|
/** Properties on element prototypes that are purely configuration. */
|
|
var ELEMENT_CONFIGURATION = [
|
|
'attached',
|
|
'attributeChanged',
|
|
'configure',
|
|
'constructor',
|
|
'created',
|
|
'detached',
|
|
'enableCustomStyleProperties',
|
|
'extends',
|
|
'hostAttributes',
|
|
'is',
|
|
'listeners',
|
|
'mixins',
|
|
'properties',
|
|
'ready',
|
|
'registered'
|
|
];
|
|
|
|
/** Tags understood by the annotation process, to be removed during `clean`. */
|
|
var HANDLED_TAGS = [
|
|
'param',
|
|
'return',
|
|
'type',
|
|
];
|
|
|
|
/**
|
|
* Annotates Hydrolysis descriptors, processing any `desc` properties as JSDoc.
|
|
*
|
|
* You probably want to use a more specialized version of this, such as
|
|
* `annotateElement`.
|
|
*
|
|
* Processed JSDoc values will be made available via the `jsdoc` property on a
|
|
* descriptor node.
|
|
*
|
|
* @param {Object} descriptor The descriptor node to process.
|
|
* @return {Object} The descriptor that was given.
|
|
*/
|
|
function annotate(descriptor) {
|
|
if (!descriptor || descriptor.jsdoc) return descriptor;
|
|
|
|
if (typeof descriptor.desc === 'string') {
|
|
descriptor.jsdoc = jsdoc.parseJsdoc(descriptor.desc);
|
|
// We want to present the normalized form of a descriptor.
|
|
descriptor.jsdoc.orig = descriptor.desc;
|
|
descriptor.desc = descriptor.jsdoc.description;
|
|
}
|
|
|
|
return descriptor;
|
|
}
|
|
|
|
/**
|
|
* Annotates @event, @hero, & @demo tags
|
|
*/
|
|
function annotateElementHeader(descriptor) {
|
|
if (descriptor.events) {
|
|
descriptor.events.forEach(function(event) {
|
|
_annotateEvent(event);
|
|
});
|
|
descriptor.events.sort( function(a,b) {
|
|
return a.name.localeCompare(b.name);
|
|
});
|
|
}
|
|
descriptor.demos = [];
|
|
if (descriptor.jsdoc && descriptor.jsdoc.tags) {
|
|
descriptor.jsdoc.tags.forEach( function(tag) {
|
|
switch(tag.tag) {
|
|
case 'hero':
|
|
descriptor.hero = tag.name || 'hero.png';
|
|
break;
|
|
case 'demo':
|
|
descriptor.demos.push({
|
|
desc: tag.description || 'demo',
|
|
path: tag.name || 'demo/index.html'
|
|
});
|
|
}
|
|
});
|
|
}
|
|
}
|
|
|
|
function matchByName(propa, propb) {
|
|
return propa.name == propb.name;
|
|
}
|
|
|
|
function copyProperties(from, to, behaviorsByName) {
|
|
if (from.properties) {
|
|
from.properties.forEach(function(fromProp){
|
|
for (var toProp, i = 0; i < to.properties.length; i++) {
|
|
toProp = to.properties[i];
|
|
if (fromProp.name === toProp.name) {
|
|
return;
|
|
}
|
|
}
|
|
var newProp = {__fromBehavior: from.is};
|
|
if (fromProp.__fromBehavior) {
|
|
return;
|
|
}
|
|
Object.keys(fromProp).forEach(function(propertyField){
|
|
newProp[propertyField] = fromProp[propertyField];
|
|
});
|
|
to.properties.push(newProp);
|
|
});
|
|
from.events.forEach(function(fromEvent){
|
|
for (var toEvent, i = 0; i < to.events.length; i++) {
|
|
toEvent = to.events[i];
|
|
if (fromEvent.name === toEvent.name) {
|
|
return;
|
|
}
|
|
}
|
|
if (fromEvent.__fromBehavior) {
|
|
return;
|
|
}
|
|
var newEvent = Object.create(fromEvent);
|
|
newEvent.__fromBehavior = from.is;
|
|
to.events.push(newEvent);
|
|
});
|
|
}
|
|
if (!from.behaviors) {
|
|
return;
|
|
}
|
|
for (var i = from.behaviors.length - 1; i >= 0; i--) {
|
|
var behavior = from.behaviors[i];
|
|
var definedBehavior = behaviorsByName[behavior] || behaviorsByName[behavior.symbol];
|
|
if (!definedBehavior) {
|
|
console.warn("Behavior " + behavior + " not found when mixing " +
|
|
"properties into " + to.is + "!");
|
|
return;
|
|
}
|
|
copyProperties(definedBehavior, to, behaviorsByName);
|
|
}
|
|
}
|
|
|
|
function mixinBehaviors(descriptor, behaviorsByName) {
|
|
if (descriptor.behaviors) {
|
|
for (var i = descriptor.behaviors.length - 1; i >= 0; i--) {
|
|
var behavior = descriptor.behaviors[i];
|
|
if (!behaviorsByName[behavior]) {
|
|
console.warn("Behavior " + behavior + " not found when mixing " +
|
|
"properties into " + descriptor.is + "!");
|
|
break;
|
|
}
|
|
var definedBehavior = behaviorsByName[behavior];
|
|
copyProperties(definedBehavior, descriptor, behaviorsByName);
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Annotates documentation found within a Hydrolysis element descriptor. Also
|
|
* supports behaviors.
|
|
*
|
|
* If the element was processed via `hydrolize`, the element's documentation
|
|
* will also be extracted via its <dom-module>.
|
|
*
|
|
* @param {Object} descriptor The element descriptor.
|
|
* @return {Object} The descriptor that was given.
|
|
*/
|
|
function annotateElement(descriptor, behaviorsByName) {
|
|
if (!descriptor.desc && descriptor.type === 'element') {
|
|
descriptor.desc = _findElementDocs(descriptor.is,
|
|
descriptor.domModule,
|
|
descriptor.scriptElement);
|
|
}
|
|
annotate(descriptor);
|
|
|
|
// The `<dom-module>` is too low level for most needs, and it is _not_
|
|
// serializable. So we drop it now that we've extracted all the useful bits
|
|
// from it.
|
|
// TODO: Don't worry about serializability here, provide an API to get JSON.
|
|
delete descriptor.domModule;
|
|
|
|
mixinBehaviors(descriptor, behaviorsByName);
|
|
|
|
// Descriptors that should have their `desc` properties parsed as JSDoc.
|
|
descriptor.properties.forEach(function(property) {
|
|
// Feature properties are special, configuration is really just a matter of
|
|
// inheritance...
|
|
annotateProperty(property, descriptor.abstract);
|
|
});
|
|
|
|
// It may seem like overkill to always sort, but we have an assumption that
|
|
// these properties are typically being consumed by user-visible tooling.
|
|
// As such, it's good to have consistent output/ordering to aid the user.
|
|
descriptor.properties.sort(function(a, b) {
|
|
// Private properties are always last.
|
|
if (a.private && !b.private) {
|
|
return 1;
|
|
} else if (!a.private && b.private) {
|
|
return -1;
|
|
// Otherwise, we're just sorting alphabetically.
|
|
} else {
|
|
return a.name.localeCompare(b.name);
|
|
}
|
|
});
|
|
|
|
annotateElementHeader(descriptor);
|
|
|
|
return descriptor;
|
|
}
|
|
|
|
/**
|
|
* Annotates behavior descriptor.
|
|
* @param {Object} descriptor behavior descriptor
|
|
* @return {Object} descriptor passed in as param
|
|
*/
|
|
function annotateBehavior(descriptor, behaviorsByName) {
|
|
annotate(descriptor);
|
|
annotateElementHeader(descriptor);
|
|
|
|
return descriptor;
|
|
}
|
|
|
|
/**
|
|
* Annotates event documentation
|
|
*/
|
|
function _annotateEvent(descriptor) {
|
|
annotate(descriptor);
|
|
// process @event
|
|
var eventTag = jsdoc.getTag(descriptor.jsdoc, 'event');
|
|
descriptor.name = eventTag ? eventTag.description : "N/A";
|
|
|
|
// process @params
|
|
descriptor.params = (descriptor.jsdoc.tags || [])
|
|
.filter( function(tag) {
|
|
return tag.tag === 'param';
|
|
})
|
|
.map( function(tag) {
|
|
return {
|
|
type: tag.type || "N/A",
|
|
desc: tag.description,
|
|
name: tag.name || "N/A"
|
|
};
|
|
});
|
|
// process @params
|
|
return descriptor;
|
|
}
|
|
|
|
/**
|
|
* Annotates documentation found about a Hydrolysis property descriptor.
|
|
*
|
|
* @param {Object} descriptor The property descriptor.
|
|
* @param {boolean} ignoreConfiguration If true, `configuration` is not set.
|
|
* @return {Object} The descriptior that was given.
|
|
*/
|
|
function annotateProperty(descriptor, ignoreConfiguration) {
|
|
annotate(descriptor);
|
|
if (descriptor.name[0] === '_' || jsdoc.hasTag(descriptor.jsdoc, 'private')) {
|
|
descriptor.private = true;
|
|
}
|
|
|
|
if (!ignoreConfiguration && ELEMENT_CONFIGURATION.indexOf(descriptor.name) !== -1) {
|
|
descriptor.private = true;
|
|
descriptor.configuration = true;
|
|
}
|
|
|
|
// @type JSDoc wins
|
|
descriptor.type = jsdoc.getTag(descriptor.jsdoc, 'type', 'type') || descriptor.type;
|
|
|
|
if (descriptor.type.match(/^function/i)) {
|
|
_annotateFunctionProperty(descriptor);
|
|
}
|
|
|
|
// @default JSDoc wins
|
|
var defaultTag = jsdoc.getTag(descriptor.jsdoc, 'default');
|
|
if (defaultTag !== null) {
|
|
var newDefault = (defaultTag.name || '') + (defaultTag.description || '');
|
|
if (newDefault !== '') {
|
|
descriptor.default = newDefault;
|
|
}
|
|
}
|
|
|
|
return descriptor;
|
|
}
|
|
|
|
/** @param {Object} descriptor */
|
|
function _annotateFunctionProperty(descriptor) {
|
|
descriptor.function = true;
|
|
|
|
var returnTag = jsdoc.getTag(descriptor.jsdoc, 'return');
|
|
if (returnTag) {
|
|
descriptor.return = {
|
|
type: returnTag.type,
|
|
desc: returnTag.description,
|
|
};
|
|
}
|
|
|
|
var paramsByName = {};
|
|
(descriptor.params || []).forEach(function(param) {
|
|
paramsByName[param.name] = param;
|
|
});
|
|
(descriptor.jsdoc && descriptor.jsdoc.tags || []).forEach(function(tag) {
|
|
if (tag.tag !== 'param') return;
|
|
var param = paramsByName[tag.name];
|
|
if (!param) {
|
|
return;
|
|
}
|
|
|
|
param.type = tag.type || param.type;
|
|
param.desc = tag.description;
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Converts raw features into an abstract `Polymer.Base` element.
|
|
*
|
|
* Note that docs on this element _are not processed_. You must call
|
|
* `annotateElement` on it yourself if you wish that.
|
|
*
|
|
* @param {Array<FeatureDescriptor>} features
|
|
* @return {ElementDescriptor}
|
|
*/
|
|
function featureElement(features) {
|
|
var properties = features.reduce(function(result, feature) {
|
|
return result.concat(feature.properties);
|
|
}, []);
|
|
|
|
return {
|
|
type: 'element',
|
|
is: 'Polymer.Base',
|
|
abstract: true,
|
|
properties: properties,
|
|
desc: '`Polymer.Base` acts as a base prototype for all Polymer ' +
|
|
'elements. It is composed via various calls to ' +
|
|
'`Polymer.Base._addFeature()`.\n' +
|
|
'\n' +
|
|
'The properties reflected here are the combined view of all ' +
|
|
'features found in this library. There may be more properties ' +
|
|
'added via other libraries, as well.',
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Cleans redundant properties from a descriptor, assuming that you have already
|
|
* called `annotate`.
|
|
*
|
|
* @param {Object} descriptor
|
|
*/
|
|
function clean(descriptor) {
|
|
if (!descriptor.jsdoc) return;
|
|
// The doctext was written to `descriptor.desc`
|
|
delete descriptor.jsdoc.description;
|
|
delete descriptor.jsdoc.orig;
|
|
|
|
var cleanTags = [];
|
|
(descriptor.jsdoc.tags || []).forEach(function(tag) {
|
|
// Drop any tags we've consumed.
|
|
if (HANDLED_TAGS.indexOf(tag.tag) !== -1) return;
|
|
cleanTags.push(tag);
|
|
});
|
|
|
|
if (cleanTags.length === 0) {
|
|
// No tags? no docs left!
|
|
delete descriptor.jsdoc;
|
|
} else {
|
|
descriptor.jsdoc.tags = cleanTags;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Cleans redundant properties from an element, assuming that you have already
|
|
* called `annotateElement`.
|
|
*
|
|
* @param {ElementDescriptor|BehaviorDescriptor} element
|
|
*/
|
|
function cleanElement(element) {
|
|
clean(element);
|
|
element.properties.forEach(cleanProperty);
|
|
}
|
|
|
|
/**
|
|
* Cleans redundant properties from a property, assuming that you have already
|
|
* called `annotateProperty`.
|
|
*
|
|
* @param {PropertyDescriptor} property
|
|
*/
|
|
function cleanProperty(property) {
|
|
clean(property);
|
|
}
|
|
|
|
/**
|
|
* Parse elements defined only in comments.
|
|
* @param {comments} Array<string> A list of comments to parse.
|
|
* @return {ElementDescriptor} A list of pseudo-elements.
|
|
*/
|
|
function parsePseudoElements(comments) {
|
|
var elements = [];
|
|
comments.forEach(function(comment) {
|
|
var parsed = jsdoc.parseJsdoc(comment);
|
|
var pseudoTag = jsdoc.getTag(parsed, 'pseudoElement', 'name');
|
|
if (pseudoTag) {
|
|
parsed.is = pseudoTag;
|
|
parsed.jsdoc = {description: parsed.description, tags: parsed.tags};
|
|
parsed.properties = [];
|
|
parsed.desc = parsed.description;
|
|
parsed.description = undefined;
|
|
parsed.tags = undefined;
|
|
annotateElementHeader(parsed);
|
|
elements.push(parsed);
|
|
}
|
|
});
|
|
return elements;
|
|
}
|
|
|
|
/**
|
|
* @param {string} elementId
|
|
* @param {DocumentAST} domModule
|
|
* @param {DocumentAST} scriptElement The script that the element was defined in.
|
|
*/
|
|
function _findElementDocs(elementId, domModule, scriptElement) {
|
|
// Note that we concatenate docs from all sources if we find them.
|
|
// element can be defined in:
|
|
// html comment right before dom-module
|
|
// html commnet right before script defining the module, if dom-module is empty
|
|
|
|
var found = [];
|
|
|
|
// Do we have a HTML comment on the `<dom-module>` or `<script>`?
|
|
//
|
|
// Confusingly, with our current style, the comment will be attached to
|
|
// `<head>`, rather than being a sibling to the `<dom-module>`
|
|
var searchRoot = domModule || scriptElement;
|
|
var parents = dom5.nodeWalkAllPrior(searchRoot, dom5.isCommentNode);
|
|
var comment = parents.length > 0 ? parents[0] : null;
|
|
if (comment && comment.data) {
|
|
found.push(comment.data);
|
|
}
|
|
if (found.length === 0) return null;
|
|
return found
|
|
.filter(function(comment) {
|
|
// skip @license comments
|
|
if (comment && comment.indexOf('@license' === -1)) {
|
|
return true;
|
|
}
|
|
else {
|
|
return false;
|
|
}
|
|
})
|
|
.map(jsdoc.unindent).join('\n');
|
|
}
|
|
|
|
function _findLastChildNamed(name, parent) {
|
|
var children = parent.childNodes;
|
|
for (var i = children.length - 1, child; i >= 0; i--) {
|
|
child = children[i];
|
|
if (child.nodeName === name) return child;
|
|
}
|
|
return null;
|
|
}
|
|
|
|
// TODO(nevir): parse5-utils!
|
|
function _getNodeAttribute(node, name) {
|
|
for (var i = 0, attr; i < node.attrs.length; i++) {
|
|
attr = node.attrs[i];
|
|
if (attr.name === name) {
|
|
return attr.value;
|
|
}
|
|
}
|
|
}
|
|
|
|
module.exports = {
|
|
annotate: annotate,
|
|
annotateElement: annotateElement,
|
|
annotateBehavior: annotateBehavior,
|
|
clean: clean,
|
|
cleanElement: cleanElement,
|
|
featureElement: featureElement,
|
|
parsePseudoElements: parsePseudoElements
|
|
};
|