@enterthenamehere/esdoc
Version:
Good Documentation Generator For JavaScript, updated for new decade
107 lines (102 loc) • 12.6 kB
JavaScript
;
Object.defineProperty(exports, "__esModule", {
value: true
});
exports.default = void 0;
/**
* Doc Comment Parser class.
*
* @example
* for (let comment of node.leadingComments) {
* let tags = CommentParser.parse(comment);
* console.log(tags);
* }
*/
class CommentParser {
/**
* parse comment to tags.
* @param {ASTNode} commentNode - comment node.
* @param {string} commentNode.value - comment body.
* @param {string} commentNode.type - CommentBlock or CommentLine.
* @returns {Tag[]} parsed comment.
*/
static parse(commentNode) {
if (!this.isESDoc(commentNode)) return [];
var comment = commentNode.value;
// TODO: refactor
comment = comment.replace(/\r\n/gm, '\n'); // for windows
comment = comment.replace(/^[\t ]*/gm, ''); // remove line head space
comment = comment.replace(/^\*[\t ]?/, ''); // remove first '*'
comment = comment.replace(/[\t ]$/, ''); // remove last space
comment = comment.replace(/^\*[\t ]?/gm, ''); // remove line head '*'
if (comment.charAt(0) !== '@') comment = "@desc ".concat(comment); // auto insert @desc
comment = comment.replace(/[\t ]*$/, ''); // remove tail space.
comment = comment.replace(/```(?:[\0-\uD7FF\uE000-\uFFFF]|[\uD800-\uDBFF][\uDC00-\uDFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?:[^\uD800-\uDBFF]|^)[\uDC00-\uDFFF])*?```/g, match => {
return match.replace(/@/g, '\\ESCAPED_AT\\');
}); // escape code in descriptions
comment = comment.replace(/^[\t ]*(@[0-9A-Z_a-z]+)$/gm, '$1 \\TRUE'); // auto insert tag text to non-text tag (e.g. @interface)
comment = comment.replace(/^[\t ]*(@[0-9A-Z_a-z]+)[\t ]((?:[\0-\t\x0B\f\x0E-\u2027\u202A-\uD7FF\uE000-\uFFFF]|[\uD800-\uDBFF][\uDC00-\uDFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?:[^\uD800-\uDBFF]|^)[\uDC00-\uDFFF])*)/gm, '\\Z$1\\Z$2'); // insert separator (\\Z@tag\\Ztext)
var lines = comment.split('\\Z');
var tagName = '';
var tagValue = '';
var tags = [];
for (var i = 0; i < lines.length; i++) {
var line = lines[i];
if (line.charAt(0) === '@') {
tagName = line;
var nextLine = lines[i + 1];
if (nextLine.charAt(0) === '@') {
tagValue = '';
} else {
tagValue = nextLine;
i++;
}
tagValue = tagValue.replace('\\TRUE', '').replace(/\\ESCAPED_AT\\/g, '@').replace(/^\n/, '').replace(/\n*$/, '');
tags.push({
tagName,
tagValue
});
}
}
return tags;
}
/**
* parse node to tags.
* @param {ASTNode} node - node.
* @returns {{tags: Tag[], commentNode: CommentNode}} parsed comment.
*/
static parseFromNode(node) {
if (!node.leadingComments) node.leadingComments = [{
type: 'CommentBlock',
value: ''
}];
var commentNode = node.leadingComments[node.leadingComments.length - 1];
var tags = this.parse(commentNode);
return {
tags,
commentNode
};
}
/**
* judge doc comment or not.
* @param {ASTNode} commentNode - comment node.
* @returns {boolean} if true, this comment node is doc comment.
*/
static isESDoc(commentNode) {
if (commentNode.type !== 'CommentBlock') return false;
return commentNode.value.charAt(0) === '*';
}
/**
* build comment from tags
* @param {Tag[]} tags
* @returns {string} block comment value.
*/
static buildComment(tags) {
return tags.reduce((comment, tag) => {
var line = tag.tagValue.replace(/\n/g, '\n * ');
return "".concat(comment, " * ").concat(tag.tagName, " \n * ").concat(line, " \n");
}, '*\n');
}
}
exports.default = CommentParser;
//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJuYW1lcyI6WyJDb21tZW50UGFyc2VyIiwicGFyc2UiLCJjb21tZW50Tm9kZSIsImlzRVNEb2MiLCJjb21tZW50IiwidmFsdWUiLCJyZXBsYWNlIiwiY2hhckF0IiwiY29uY2F0IiwibWF0Y2giLCJsaW5lcyIsInNwbGl0IiwidGFnTmFtZSIsInRhZ1ZhbHVlIiwidGFncyIsImkiLCJsZW5ndGgiLCJsaW5lIiwibmV4dExpbmUiLCJwdXNoIiwicGFyc2VGcm9tTm9kZSIsIm5vZGUiLCJsZWFkaW5nQ29tbWVudHMiLCJ0eXBlIiwiYnVpbGRDb21tZW50IiwicmVkdWNlIiwidGFnIiwiZXhwb3J0cyIsImRlZmF1bHQiXSwic291cmNlcyI6WyIuLi8uLi9zcmMvUGFyc2VyL0NvbW1lbnRQYXJzZXIuanMiXSwic291cmNlc0NvbnRlbnQiOlsiLyoqXHJcbiAqIERvYyBDb21tZW50IFBhcnNlciBjbGFzcy5cclxuICpcclxuICogQGV4YW1wbGVcclxuICogZm9yIChsZXQgY29tbWVudCBvZiBub2RlLmxlYWRpbmdDb21tZW50cykge1xyXG4gKiAgIGxldCB0YWdzID0gQ29tbWVudFBhcnNlci5wYXJzZShjb21tZW50KTtcclxuICogICBjb25zb2xlLmxvZyh0YWdzKTtcclxuICogfVxyXG4gKi9cclxuZXhwb3J0IGRlZmF1bHQgY2xhc3MgQ29tbWVudFBhcnNlciB7XHJcbiAgLyoqXHJcbiAgICogcGFyc2UgY29tbWVudCB0byB0YWdzLlxyXG4gICAqIEBwYXJhbSB7QVNUTm9kZX0gY29tbWVudE5vZGUgLSBjb21tZW50IG5vZGUuXHJcbiAgICogQHBhcmFtIHtzdHJpbmd9IGNvbW1lbnROb2RlLnZhbHVlIC0gY29tbWVudCBib2R5LlxyXG4gICAqIEBwYXJhbSB7c3RyaW5nfSBjb21tZW50Tm9kZS50eXBlIC0gQ29tbWVudEJsb2NrIG9yIENvbW1lbnRMaW5lLlxyXG4gICAqIEByZXR1cm5zIHtUYWdbXX0gcGFyc2VkIGNvbW1lbnQuXHJcbiAgICovXHJcbiAgc3RhdGljIHBhcnNlKGNvbW1lbnROb2RlKSB7XHJcbiAgICBpZiAoIXRoaXMuaXNFU0RvYyhjb21tZW50Tm9kZSkpIHJldHVybiBbXTtcclxuXHJcbiAgICBsZXQgY29tbWVudCA9IGNvbW1lbnROb2RlLnZhbHVlO1xyXG5cclxuICAgIC8vIFRPRE86IHJlZmFjdG9yXHJcbiAgICBjb21tZW50ID0gY29tbWVudC5yZXBsYWNlKC9cXHJcXG4vZ211LCAnXFxuJyk7IC8vIGZvciB3aW5kb3dzXHJcbiAgICBjb21tZW50ID0gY29tbWVudC5yZXBsYWNlKC9eW1xcdCBdKi9nbXUsICcnKTsgLy8gcmVtb3ZlIGxpbmUgaGVhZCBzcGFjZVxyXG4gICAgY29tbWVudCA9IGNvbW1lbnQucmVwbGFjZSgvXlxcKltcXHQgXT8vdSwgJycpOyAvLyByZW1vdmUgZmlyc3QgJyonXHJcbiAgICBjb21tZW50ID0gY29tbWVudC5yZXBsYWNlKC9bXFx0IF0kL3UsICcnKTsgLy8gcmVtb3ZlIGxhc3Qgc3BhY2VcclxuICAgIGNvbW1lbnQgPSBjb21tZW50LnJlcGxhY2UoL15cXCpbXFx0IF0/L2dtdSwgJycpOyAvLyByZW1vdmUgbGluZSBoZWFkICcqJ1xyXG4gICAgaWYgKGNvbW1lbnQuY2hhckF0KDApICE9PSAnQCcpIGNvbW1lbnQgPSBgQGRlc2MgJHtjb21tZW50fWA7IC8vIGF1dG8gaW5zZXJ0IEBkZXNjXHJcbiAgICBjb21tZW50ID0gY29tbWVudC5yZXBsYWNlKC9bXFx0IF0qJC91LCAnJyk7IC8vIHJlbW92ZSB0YWlsIHNwYWNlLlxyXG4gICAgY29tbWVudCA9IGNvbW1lbnQucmVwbGFjZSgvYGBgW1xcc1xcU10qP2BgYC9ndSwgKG1hdGNoKSA9PiB7IHJldHVybiBtYXRjaC5yZXBsYWNlKC9AL2d1LCAnXFxcXEVTQ0FQRURfQVRcXFxcJyk7IH0pOyAvLyBlc2NhcGUgY29kZSBpbiBkZXNjcmlwdGlvbnNcclxuICAgIGNvbW1lbnQgPSBjb21tZW50LnJlcGxhY2UoL15bXFx0IF0qKEBcXHcrKSQvZ211LCAnJDEgXFxcXFRSVUUnKTsgLy8gYXV0byBpbnNlcnQgdGFnIHRleHQgdG8gbm9uLXRleHQgdGFnIChlLmcuIEBpbnRlcmZhY2UpXHJcbiAgICBjb21tZW50ID0gY29tbWVudC5yZXBsYWNlKC9eW1xcdCBdKihAXFx3KylbXFx0IF0oLiopL2dtdSwgJ1xcXFxaJDFcXFxcWiQyJyk7IC8vIGluc2VydCBzZXBhcmF0b3IgKFxcXFxaQHRhZ1xcXFxadGV4dClcclxuICAgIGNvbnN0IGxpbmVzID0gY29tbWVudC5zcGxpdCgnXFxcXFonKTtcclxuXHJcbiAgICBsZXQgdGFnTmFtZSA9ICcnO1xyXG4gICAgbGV0IHRhZ1ZhbHVlID0gJyc7XHJcbiAgICBjb25zdCB0YWdzID0gW107XHJcbiAgICBmb3IgKGxldCBpID0gMDsgaSA8IGxpbmVzLmxlbmd0aDsgaSsrKSB7XHJcbiAgICAgIGNvbnN0IGxpbmUgPSBsaW5lc1tpXTtcclxuICAgICAgaWYgKGxpbmUuY2hhckF0KDApID09PSAnQCcpIHtcclxuICAgICAgICB0YWdOYW1lID0gbGluZTtcclxuICAgICAgICBjb25zdCBuZXh0TGluZSA9IGxpbmVzW2kgKyAxXTtcclxuICAgICAgICBpZiAobmV4dExpbmUuY2hhckF0KDApID09PSAnQCcpIHtcclxuICAgICAgICAgIHRhZ1ZhbHVlID0gJyc7XHJcbiAgICAgICAgfSBlbHNlIHtcclxuICAgICAgICAgIHRhZ1ZhbHVlID0gbmV4dExpbmU7XHJcbiAgICAgICAgICBpKys7XHJcbiAgICAgICAgfVxyXG4gICAgICAgIHRhZ1ZhbHVlID0gdGFnVmFsdWUucmVwbGFjZSgnXFxcXFRSVUUnLCAnJylcclxuICAgICAgICAgIC5yZXBsYWNlKC9cXFxcRVNDQVBFRF9BVFxcXFwvZ3UsICdAJylcclxuICAgICAgICAgIC5yZXBsYWNlKC9eXFxuL3UsICcnKVxyXG4gICAgICAgICAgLnJlcGxhY2UoL1xcbiokL3UsICcnKTtcclxuICAgICAgICB0YWdzLnB1c2goe3RhZ05hbWUsIHRhZ1ZhbHVlfSk7XHJcbiAgICAgIH1cclxuICAgIH1cclxuICAgIHJldHVybiB0YWdzO1xyXG4gIH1cclxuXHJcbiAgLyoqXHJcbiAgICogcGFyc2Ugbm9kZSB0byB0YWdzLlxyXG4gICAqIEBwYXJhbSB7QVNUTm9kZX0gbm9kZSAtIG5vZGUuXHJcbiAgICogQHJldHVybnMge3t0YWdzOiBUYWdbXSwgY29tbWVudE5vZGU6IENvbW1lbnROb2RlfX0gcGFyc2VkIGNvbW1lbnQuXHJcbiAgICovXHJcbiAgc3RhdGljIHBhcnNlRnJvbU5vZGUobm9kZSkge1xyXG4gICAgaWYgKCFub2RlLmxlYWRpbmdDb21tZW50cykgbm9kZS5sZWFkaW5nQ29tbWVudHMgPSBbe3R5cGU6ICdDb21tZW50QmxvY2snLCB2YWx1ZTogJyd9XTtcclxuICAgIGNvbnN0IGNvbW1lbnROb2RlID0gbm9kZS5sZWFkaW5nQ29tbWVudHNbbm9kZS5sZWFkaW5nQ29tbWVudHMubGVuZ3RoIC0gMV07XHJcbiAgICBjb25zdCB0YWdzID0gdGhpcy5wYXJzZShjb21tZW50Tm9kZSk7XHJcblxyXG4gICAgcmV0dXJuIHt0YWdzLCBjb21tZW50Tm9kZX07XHJcbiAgfVxyXG5cclxuICAvKipcclxuICAgKiBqdWRnZSBkb2MgY29tbWVudCBvciBub3QuXHJcbiAgICogQHBhcmFtIHtBU1ROb2RlfSBjb21tZW50Tm9kZSAtIGNvbW1lbnQgbm9kZS5cclxuICAgKiBAcmV0dXJucyB7Ym9vbGVhbn0gaWYgdHJ1ZSwgdGhpcyBjb21tZW50IG5vZGUgaXMgZG9jIGNvbW1lbnQuXHJcbiAgICovXHJcbiAgc3RhdGljIGlzRVNEb2MoY29tbWVudE5vZGUpIHtcclxuICAgIGlmIChjb21tZW50Tm9kZS50eXBlICE9PSAnQ29tbWVudEJsb2NrJykgcmV0dXJuIGZhbHNlO1xyXG4gICAgcmV0dXJuIGNvbW1lbnROb2RlLnZhbHVlLmNoYXJBdCgwKSA9PT0gJyonO1xyXG4gIH1cclxuXHJcbiAgLyoqXHJcbiAgICogYnVpbGQgY29tbWVudCBmcm9tIHRhZ3NcclxuICAgKiBAcGFyYW0ge1RhZ1tdfSB0YWdzXHJcbiAgICogQHJldHVybnMge3N0cmluZ30gYmxvY2sgY29tbWVudCB2YWx1ZS5cclxuICAgKi9cclxuICBzdGF0aWMgYnVpbGRDb21tZW50KHRhZ3MpIHtcclxuICAgIHJldHVybiB0YWdzLnJlZHVjZSgoY29tbWVudCwgdGFnKSA9PiB7XHJcbiAgICAgIGNvbnN0IGxpbmUgPSB0YWcudGFnVmFsdWUucmVwbGFjZSgvXFxuL2d1LCAnXFxuICogJyk7XHJcbiAgICAgIHJldHVybiBgJHtjb21tZW50fSAqICR7dGFnLnRhZ05hbWV9IFxcbiAqICR7bGluZX0gXFxuYDtcclxuICAgIH0sICcqXFxuJyk7XHJcbiAgfVxyXG59XHJcbiJdLCJtYXBwaW5ncyI6Ijs7Ozs7O0FBQUE7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ2UsTUFBTUEsYUFBYSxDQUFDO0VBQ2pDO0FBQ0Y7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0VBQ0UsT0FBT0MsS0FBS0EsQ0FBQ0MsV0FBVyxFQUFFO0lBQ3hCLElBQUksQ0FBQyxJQUFJLENBQUNDLE9BQU8sQ0FBQ0QsV0FBVyxDQUFDLEVBQUUsT0FBTyxFQUFFO0lBRXpDLElBQUlFLE9BQU8sR0FBR0YsV0FBVyxDQUFDRyxLQUFLOztJQUUvQjtJQUNBRCxPQUFPLEdBQUdBLE9BQU8sQ0FBQ0UsT0FBTyxDQUFDLFFBQVMsRUFBRSxJQUFJLENBQUMsQ0FBQyxDQUFDO0lBQzVDRixPQUFPLEdBQUdBLE9BQU8sQ0FBQ0UsT0FBTyxDQUFDLFdBQVksRUFBRSxFQUFFLENBQUMsQ0FBQyxDQUFDO0lBQzdDRixPQUFPLEdBQUdBLE9BQU8sQ0FBQ0UsT0FBTyxDQUFDLFdBQVksRUFBRSxFQUFFLENBQUMsQ0FBQyxDQUFDO0lBQzdDRixPQUFPLEdBQUdBLE9BQU8sQ0FBQ0UsT0FBTyxDQUFDLFFBQVMsRUFBRSxFQUFFLENBQUMsQ0FBQyxDQUFDO0lBQzFDRixPQUFPLEdBQUdBLE9BQU8sQ0FBQ0UsT0FBTyxDQUFDLGFBQWMsRUFBRSxFQUFFLENBQUMsQ0FBQyxDQUFDO0lB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