fbdbbfb7a7
This change adds a stability value to the api annotation, with 'experimental' as default value. enum, typedef and event annotations are never exportable, but api annotations are needed there to make them appear in the docs. Nested typedefs are no longer inlined recursively, because the resulting tables get too wide with the current template.
109 lines
3.4 KiB
JavaScript
109 lines
3.4 KiB
JavaScript
/*
|
|
* This is a hack to prevent inheritDoc tags from entirely removing
|
|
* documentation of the method that inherits the documentation.
|
|
*
|
|
* TODO: Remove this hack when https://github.com/jsdoc3/jsdoc/issues/53
|
|
* is addressed.
|
|
*/
|
|
|
|
|
|
exports.defineTags = function(dictionary) {
|
|
dictionary.defineTag('inheritDoc', {
|
|
mustHaveValue: false,
|
|
canHaveType: false,
|
|
canHaveName: false,
|
|
onTagged: function(doclet, tag) {
|
|
doclet.inheritdoc = true;
|
|
}
|
|
});
|
|
};
|
|
|
|
|
|
var lookup = {};
|
|
var incompleteByClass = {};
|
|
var keepKeys = ['comment', 'meta', 'name', 'memberof', 'longname', 'augment',
|
|
'stability'];
|
|
|
|
exports.handlers = {
|
|
|
|
newDoclet: function(e) {
|
|
var doclet = e.doclet;
|
|
var incompletes;
|
|
if (!(doclet.longname in lookup)) {
|
|
lookup[doclet.longname] = [];
|
|
}
|
|
lookup[doclet.longname].push(doclet);
|
|
if (doclet.inheritdoc) {
|
|
if (!(doclet.memberof in incompleteByClass)) {
|
|
incompleteByClass[doclet.memberof] = [];
|
|
}
|
|
incompletes = incompleteByClass[doclet.memberof];
|
|
if (incompletes.indexOf(doclet.name) == -1) {
|
|
incompletes.push(doclet.name);
|
|
}
|
|
}
|
|
},
|
|
|
|
parseComplete: function(e) {
|
|
var ancestors, candidate, candidates, doclet, i, j, k, l, key;
|
|
var incompleteDoclet, stability, incomplete, incompletes;
|
|
var doclets = e.doclets;
|
|
for (i = doclets.length - 1; i >= 0; --i) {
|
|
doclet = doclets[i];
|
|
if (doclet.augments) {
|
|
ancestors = [].concat(doclet.augments);
|
|
}
|
|
incompletes = incompleteByClass[doclet.longname];
|
|
if (ancestors && incompletes) {
|
|
// collect ancestors from the whole hierarchy
|
|
for (j = 0; j < ancestors.length; ++j) {
|
|
candidates = lookup[ancestors[j]];
|
|
if (candidates) {
|
|
for (k = candidates.length - 1; k >= 0; --k) {
|
|
candidate = candidates[k];
|
|
if (candidate.augments) {
|
|
ancestors = ancestors.concat(candidate.augments);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
// walk through all inheritDoc members
|
|
for (j = incompletes.length - 1; j >= 0; --j) {
|
|
incomplete = incompletes[j];
|
|
candidates = lookup[doclet.longname + '#' + incomplete];
|
|
if (candidates) {
|
|
// get the incomplete doclet that needs to be augmented
|
|
for (k = candidates.length - 1; k >= 0; --k) {
|
|
incompleteDoclet = candidates[k];
|
|
if (incompleteDoclet.inheritdoc) {
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
// find the documented ancestor
|
|
for (k = ancestors.length - 1; k >= 0; --k) {
|
|
candidates = lookup[ancestors[k] + '#' + incomplete];
|
|
if (candidates) {
|
|
for (l = candidates.length - 1; l >= 0; --l) {
|
|
candidate = candidates[l];
|
|
if (candidate && !candidate.inheritdoc) {
|
|
stability = candidate.stability || incompleteDoclet.stability
|
|
if (stability) {
|
|
incompleteDoclet.stability = stability;
|
|
for (key in candidate) {
|
|
if (candidate.hasOwnProperty(key) &&
|
|
keepKeys.indexOf(key) == -1) {
|
|
incompleteDoclet[key] = candidate[key];
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
}; |