archive-gh-me/jsdoc
1
0
Fork 0
mirror of https://github.com/jsdoc/jsdoc.git synced 2025-12-08 19:46:11 +00:00
Code Issues Projects Releases Wiki Activity

clean up module requires

Browse Source
This commit is contained in:
Jeff Williams 2019-07-27 16:01:52 -07:00
parent 843d707f1b
commit b0d42e80be
16 changed files with 157 additions and 213 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
gulpfile.js
View File

@ -1,6 +1,6 @@
/* eslint max-nested-callbacks: 0 */
const eslint = require('gulp-eslint');
const exec = require('child_process').exec;
const { exec } = require('child_process');
const gulp = require('gulp');
const jsonEditor = require('gulp-json-editor');
const path = require('path');

2
lib/jsdoc/borrow.js
View File

@ -3,7 +3,7 @@
* @module jsdoc/borrow
*/
const doop = require('jsdoc/util/doop');
const SCOPE = require('jsdoc/name').SCOPE;
const { SCOPE } = require('jsdoc/name');
function cloneBorrowedDoclets({borrowed, longname}, doclets) {
borrowed.forEach(({from, as}) => {

53
lib/jsdoc/doclet.js
View File

@ -2,23 +2,13 @@
* @module jsdoc/doclet
*/
const _ = require('lodash');
const jsdoc = {
env: require('jsdoc/env'),
name: require('jsdoc/name'),
src: {
astnode: require('jsdoc/src/astnode'),
Syntax: require('jsdoc/src/syntax').Syntax
},
tag: {
Tag: require('jsdoc/tag').Tag,
dictionary: require('jsdoc/tag/dictionary')
},
util: {
doop: require('jsdoc/util/doop')
}
};
let dictionary = require('jsdoc/tag/dictionary');
const doop = require('jsdoc/util/doop');
const { isFunction } = require('jsdoc/src/astnode');
const name = require('jsdoc/name');
const path = require('jsdoc/path');
const Syntax = jsdoc.src.Syntax;
const { Syntax } = require('jsdoc/src/syntax');
const { Tag } = require('jsdoc/tag');
function applyTag(doclet, {title, value}) {
if (title === 'name') {
@ -44,7 +34,6 @@ function fakeMeta(node) {
// use the meta info about the source code to guess what the doclet kind should be
// TODO: set this elsewhere (maybe jsdoc/src/astnode.getInfo)
function codeToKind(code) {
const isFunction = jsdoc.src.astnode.isFunction;
let kind = 'member';
const node = code.node;
@ -162,13 +151,13 @@ function fixDescription(docletSrc, {code}) {
* @param {module:jsdoc/tag/dictionary.Dictionary} dict - The new tag dictionary.
*/
exports._replaceDictionary = function _replaceDictionary(dict) {
jsdoc.tag.dictionary = dict;
dictionary = dict;
require('jsdoc/tag')._replaceDictionary(dict);
require('jsdoc/util/templateHelper')._replaceDictionary(dict);
};
function removeGlobal(longname) {
const globalRegexp = new RegExp(`^${jsdoc.name.LONGNAMES.GLOBAL}\\.?`);
const globalRegexp = new RegExp(`^${name.LONGNAMES.GLOBAL}\\.?`);
return longname.replace(globalRegexp, '');
}
@ -197,7 +186,7 @@ function dooper(source, target, properties) {
break;
case 'object':
target[property] = jsdoc.util.doop(source[property]);
target[property] = doop(source[property]);
break;
@ -241,11 +230,11 @@ function copySpecificProperties(primary, secondary, target, include) {
include.forEach(property => {
if ({}.hasOwnProperty.call(primary, property) && primary[property] &&
primary[property].length) {
target[property] = jsdoc.util.doop(primary[property]);
target[property] = doop(primary[property]);
}
else if ({}.hasOwnProperty.call(secondary, property) && secondary[property] &&
secondary[property].length) {
target[property] = jsdoc.util.doop(secondary[property]);
target[property] = doop(secondary[property]);
}
});
}
@ -287,7 +276,7 @@ class Doclet {
let l;
if (!this.preserveName) {
jsdoc.name.resolve(this);
name.resolve(this);
}
if (this.name && !this.longname) {
this.setLongname(this.name);
@ -321,8 +310,8 @@ class Doclet {
* @param {string} [text] - The text of the tag being added.
*/
addTag(title, text) {
const tagDef = jsdoc.tag.dictionary.lookUp(title);
const newTag = new jsdoc.tag.Tag(title, text, this.meta);
const tagDef = dictionary.lookUp(title);
const newTag = new Tag(title, text, this.meta);
if (tagDef && tagDef.onTagged) {
tagDef.onTagged(this, newTag);
@ -347,22 +336,22 @@ class Doclet {
* @type {string}
*/
this.memberof = removeGlobal(sid)
.replace(/\.prototype/g, jsdoc.name.SCOPE.PUNC.INSTANCE);
.replace(/\.prototype/g, name.SCOPE.PUNC.INSTANCE);
}
/**
* Set the doclet's `longname` property.
*
* @param {string} name - The longname for the doclet.
* @param {string} longname - The longname for the doclet.
*/
setLongname(name) {
setLongname(longname) {
/**
* The fully resolved symbol name.
* @type {string}
*/
this.longname = removeGlobal(name);
if (jsdoc.tag.dictionary.isNamespace(this.kind)) {
this.longname = jsdoc.name.applyNamespace(this.longname, this.kind);
this.longname = removeGlobal(longname);
if (dictionary.isNamespace(this.kind)) {
this.longname = name.applyNamespace(this.longname, this.kind);
}
}
@ -377,7 +366,7 @@ class Doclet {
setScope(scope) {
let errorMessage;
let filepath;
const scopeNames = _.values(jsdoc.name.SCOPE.NAMES);
const scopeNames = _.values(name.SCOPE.NAMES);
if (!scopeNames.includes(scope)) {
filepath = getFilepath(this);

2
lib/jsdoc/opts/args.js
View File

@ -3,7 +3,7 @@
* @requires jsdoc/opts/argparser
*/
const ArgParser = require('jsdoc/opts/argparser');
const cast = require('jsdoc/util/cast').cast;
const { cast } = require('jsdoc/util/cast');
const querystring = require('querystring');
let ourOptions;

4
lib/jsdoc/src/astnode.js
View File

@ -1,9 +1,9 @@
// TODO: docs
/** @module jsdoc/src/astnode */
const cast = require('jsdoc/util/cast').cast;
const { cast } = require('jsdoc/util/cast');
const env = require('jsdoc/env');
const name = require('jsdoc/name');
const Syntax = require('jsdoc/src/syntax').Syntax;
const { Syntax } = require('jsdoc/src/syntax');
// Counter for generating unique node IDs.
let uid = 100000000;

35
lib/jsdoc/src/handlers.js
View File

@ -1,22 +1,13 @@
/**
* @module jsdoc/src/handlers
*/
const { Doclet } = require('jsdoc/doclet');
const escape = require('escape-string-regexp');
const jsdoc = {
doclet: require('jsdoc/doclet'),
name: require('jsdoc/name'),
src: {
syntax: require('jsdoc/src/syntax')
},
util: {
logger: require('jsdoc/util/logger')
}
};
const logger = require('jsdoc/util/logger');
const { SCOPE } = require('jsdoc/name');
const { Syntax } = require('jsdoc/src/syntax');
let currentModule = null;
const SCOPE_NAMES = jsdoc.name.SCOPE.NAMES;
const SCOPE_PUNC = jsdoc.name.SCOPE.PUNC;
const Syntax = jsdoc.src.syntax.Syntax;
class CurrentModule {
constructor(doclet) {
@ -40,13 +31,13 @@ function createDoclet(comment, e) {
let msg;
try {
doclet = new jsdoc.doclet.Doclet(comment, e);
doclet = new Doclet(comment, e);
}
catch (error) {
flatComment = comment.replace(/[\r\n]/g, '');
msg = `cannot create a doclet for the comment "${flatComment}": ${error.message}`;
jsdoc.util.logger.error(msg);
doclet = new jsdoc.doclet.Doclet('', e);
logger.error(msg);
doclet = new Doclet('', e);
}
return doclet;
@ -135,7 +126,7 @@ function setModuleScopeMemberOf(parser, doclet) {
// if the doclet isn't a memberof anything yet, and it's not a global, it must be a memberof
// the current module (unless we were told to skip adding memberof)
if (!doclet.memberof && doclet.scope !== SCOPE_NAMES.GLOBAL && !skipMemberof) {
if (!doclet.memberof && doclet.scope !== SCOPE.NAMES.GLOBAL && !skipMemberof) {
doclet.addTag('memberof', currentModule.longname);
}
}
@ -144,7 +135,7 @@ function setModuleScopeMemberOf(parser, doclet) {
function setDefaultScope(doclet) {
// module doclets don't get a default scope
if (!doclet.scope && doclet.kind !== 'module') {
doclet.setScope(SCOPE_NAMES.GLOBAL);
doclet.setScope(SCOPE.NAMES.GLOBAL);
}
}
@ -205,7 +196,7 @@ function findSymbolMemberof(parser, doclet, astNode, nameStartsWith, trailingPun
// module.exports = MyModuleObject; MyModuleObject.bar = 1;
if (nameStartsWith !== 'this' && currentModule && doclet.name !== 'module.exports') {
memberof = currentModule.longname;
scopePunc = SCOPE_PUNC.STATIC;
scopePunc = SCOPE.PUNC.STATIC;
}
// like: module.exports = 1;
else if (doclet.name === 'module.exports' && currentModule) {
@ -219,10 +210,10 @@ function findSymbolMemberof(parser, doclet, astNode, nameStartsWith, trailingPun
// this.foo = 1;
if (nameStartsWith === 'this' && currentModule && !memberof) {
memberof = currentModule.longname;
scopePunc = SCOPE_PUNC.STATIC;
scopePunc = SCOPE.PUNC.STATIC;
}
else {
scopePunc = SCOPE_PUNC.INSTANCE;
scopePunc = SCOPE.PUNC.INSTANCE;
}
}
@ -310,7 +301,7 @@ function newSymbolDoclet(parser, docletSrc, e) {
// c) we're in a module that exports only this symbol
if ( !newDoclet.memberof && newDoclet.kind !== 'module' &&
(!currentModule || currentModule.longname !== newDoclet.name) ) {
newDoclet.scope = SCOPE_NAMES.GLOBAL;
newDoclet.scope = SCOPE.NAMES.GLOBAL;
}
// handle cases where the doclet kind is auto-detected from the node type

68
lib/jsdoc/src/parser.js
View File

@ -1,24 +1,16 @@
/**
* @module jsdoc/src/parser
*/
const EventEmitter = require('events').EventEmitter;
const astNode = require('jsdoc/src/astnode');
const { conf } = require('jsdoc/env');
const doop = require('jsdoc/util/doop');
const { EventEmitter } = require('events');
const fs = require('jsdoc/fs');
const jsdoc = {
doclet: require('jsdoc/doclet'),
env: require('jsdoc/env'),
name: require('jsdoc/name'),
src: {
astnode: require('jsdoc/src/astnode'),
syntax: require('jsdoc/src/syntax')
},
util: {
doop: require('jsdoc/util/doop')
}
};
const logger = require('jsdoc/util/logger');
const name = require('jsdoc/name');
const { Syntax } = require('jsdoc/src/syntax');
const hasOwnProp = Object.prototype.hasOwnProperty;
const Syntax = jsdoc.src.syntax.Syntax;
// TODO: docs
const PARSERS = exports.PARSERS = {
@ -34,21 +26,21 @@ class DocletCache {
this._doclets = {};
}
get(name) {
if ( !hasOwnProp.call(this._doclets, name) ) {
get(itemName) {
if ( !hasOwnProp.call(this._doclets, itemName) ) {
return null;
}
// always return the most recent doclet
return this._doclets[name][this._doclets[name].length - 1];
return this._doclets[itemName][this._doclets[itemName].length - 1];
}
put(name, value) {
if ( !hasOwnProp.call(this._doclets, name) ) {
this._doclets[name] = [];
put(itemName, value) {
if ( !hasOwnProp.call(this._doclets, itemName) ) {
this._doclets[itemName] = [];
}
this._doclets[name].push(value);
this._doclets[itemName].push(value);
}
}
@ -139,7 +131,7 @@ class Parser extends EventEmitter {
};
this._byNodeId = new DocletCache();
this._byLongname = new DocletCache();
this._byLongname.put(jsdoc.name.LONGNAMES.GLOBAL, {
this._byLongname.put(name.LONGNAMES.GLOBAL, {
meta: {}
});
}
@ -163,7 +155,7 @@ class Parser extends EventEmitter {
* var docs = jsdocParser.parse(myFiles);
*/
parse(sourceFiles, encoding) {
encoding = encoding || jsdoc.env.conf.encoding || 'utf8';
encoding = encoding || conf.encoding || 'utf8';
let filename = '';
let sourceCode = '';
@ -323,7 +315,7 @@ class Parser extends EventEmitter {
node.type === Syntax.ArrowFunctionExpression) &&
!this._getDocletById(node.nodeId) ) {
fakeDoclet = {
longname: jsdoc.name.LONGNAMES.ANONYMOUS,
longname: name.LONGNAMES.ANONYMOUS,
meta: {
code: e.code
}
@ -369,20 +361,20 @@ class Parser extends EventEmitter {
doclet = this._getDocletById(node.enclosingScope.nodeId);
if (!doclet) {
result.memberof = jsdoc.name.LONGNAMES.ANONYMOUS + jsdoc.name.SCOPE.PUNC.INNER;
result.memberof = name.LONGNAMES.ANONYMOUS + name.SCOPE.PUNC.INNER;
}
else {
result.memberof = doclet.longname + jsdoc.name.SCOPE.PUNC.INNER;
result.memberof = doclet.longname + name.SCOPE.PUNC.INNER;
}
}
else if (type === Syntax.ClassPrivateProperty || type === Syntax.ClassProperty) {
doclet = this._getDocletById(node.enclosingScope.nodeId);
if (!doclet) {
result.memberof = jsdoc.name.LONGNAMES.ANONYMOUS + jsdoc.name.SCOPE.PUNC.INSTANCE;
result.memberof = name.LONGNAMES.ANONYMOUS + name.SCOPE.PUNC.INSTANCE;
}
else {
result.memberof = doclet.longname + jsdoc.name.SCOPE.PUNC.INSTANCE;
result.memberof = doclet.longname + name.SCOPE.PUNC.INSTANCE;
}
}
else if (type === Syntax.MethodDefinition && node.kind === 'constructor') {
@ -390,7 +382,7 @@ class Parser extends EventEmitter {
// global classes aren't a member of anything
if (doclet.memberof) {
result.memberof = doclet.memberof + jsdoc.name.SCOPE.PUNC.INNER;
result.memberof = doclet.memberof + name.SCOPE.PUNC.INNER;
}
}
// special case for methods in classes that are returned by arrow function expressions; for
@ -403,14 +395,14 @@ class Parser extends EventEmitter {
if (doclet) {
result.memberof = doclet.longname +
(node.static === true ?
jsdoc.name.SCOPE.PUNC.STATIC :
jsdoc.name.SCOPE.PUNC.INSTANCE);
name.SCOPE.PUNC.STATIC :
name.SCOPE.PUNC.INSTANCE);
}
}
else {
// check local references for aliases
scope = node;
basename = jsdoc.name.getBasename( jsdoc.src.astnode.nodeToValue(node) );
basename = name.getBasename( astNode.nodeToValue(node) );
// walk up the scope chain until we find the scope in which the node is defined
while (scope.enclosingScope) {
@ -427,7 +419,7 @@ class Parser extends EventEmitter {
}
// do we know that it's a global?
doclet = this._getDocletByLongname(jsdoc.name.LONGNAMES.GLOBAL);
doclet = this._getDocletByLongname(name.LONGNAMES.GLOBAL);
if ( doclet && definedInScope(doclet, basename) ) {
result.memberof = doclet.meta.vars[basename];
result.basename = basename;
@ -474,8 +466,8 @@ class Parser extends EventEmitter {
// is the doclet for an instance member of a class? if so, try to get the doclet for the
// owning class
nameAtoms = jsdoc.name.shorten(doclet.longname);
if (nameAtoms.scope === jsdoc.name.SCOPE.PUNC.INSTANCE) {
nameAtoms = name.shorten(doclet.longname);
if (nameAtoms.scope === name.SCOPE.PUNC.INSTANCE) {
doclet = this._getDocletByLongname(nameAtoms.memberof);
if ( isClass(doclet) ) {
break;
@ -514,7 +506,7 @@ class Parser extends EventEmitter {
}
if (!doclet) {
result = jsdoc.name.LONGNAMES.ANONYMOUS; // TODO handle global this?
result = name.LONGNAMES.ANONYMOUS; // TODO handle global this?
}
else if (doclet.this) {
result = doclet.this;
@ -535,7 +527,7 @@ class Parser extends EventEmitter {
}
}
// like: var foo = function(n) { /** blah */ this.bar = n; }
else if ( doclet.kind === 'member' && jsdoc.src.astnode.isAssignment(node) ) {
else if ( doclet.kind === 'member' && astNode.isAssignment(node) ) {
result = doclet.longname;
}
// walk up to the closest class we can find
@ -646,7 +638,7 @@ class Parser extends EventEmitter {
// members of an enum inherit the enum's type
if (doclet.type && !e.doclet.type) {
// clone the type to prevent circular refs
e.doclet.type = jsdoc.util.doop(doclet.type);
e.doclet.type = doop(doclet.type);
}
delete e.doclet.undocumented;

2
lib/jsdoc/src/scanner.js
View File

@ -2,7 +2,7 @@
* @module jsdoc/src/scanner
* @requires module:jsdoc/fs
*/
const EventEmitter = require('events').EventEmitter;
const { EventEmitter } = require('events');
const env = require('jsdoc/env');
const fs = require('jsdoc/fs');
const logger = require('jsdoc/util/logger');

46
lib/jsdoc/src/visitor.js
View File

@ -2,20 +2,10 @@
* @module jsdoc/src/visitor
*/
// TODO: consider exporting more stuff so users can override it
const jsdoc = {
doclet: require('jsdoc/doclet'),
name: require('jsdoc/name'),
src: {
astnode: require('jsdoc/src/astnode'),
syntax: require('jsdoc/src/syntax')
},
util: {
logger: require('jsdoc/util/logger')
}
};
const Syntax = jsdoc.src.syntax.Syntax;
const astNode = require('jsdoc/src/astnode');
const combineDoclets = require('jsdoc/doclet').combine;
const { getBasename, LONGNAMES } = require('jsdoc/name');
const { Syntax } = require('jsdoc/src/syntax');
/**
* Get the raw comment string for a block comment node.
@ -289,7 +279,7 @@ function makeDefaultParamFinisher() {
typeof documentedParams[j].defaultvalue === 'undefined' &&
defaultValues[i].right.value !== '') {
documentedParams[j].defaultvalue =
jsdoc.src.astnode.nodeToValue(defaultValues[i].right);
astNode.nodeToValue(defaultValues[i].right);
}
// move to the next documented param
@ -311,7 +301,7 @@ function makeDefaultParamFinisher() {
function makeConstructorFinisher(parser) {
return e => {
let combined;
const doclet = e.doclet;
const eventDoclet = e.doclet;
let parentDoclet;
// for class declarations that are named module exports, the node that's documented is the
@ -325,11 +315,11 @@ function makeConstructorFinisher(parser) {
parentDoclet = parser._getDocletById(e.code.node.parent.parent.nodeId);
}
if (!doclet || !parentDoclet || parentDoclet.undocumented) {
if (!eventDoclet || !parentDoclet || parentDoclet.undocumented) {
return;
}
combined = jsdoc.doclet.combine(doclet, parentDoclet);
combined = combineDoclets(eventDoclet, parentDoclet);
combined.longname = parentDoclet.longname;
if (parentDoclet.memberof) {
combined.memberof = parentDoclet.memberof;
@ -337,7 +327,7 @@ function makeConstructorFinisher(parser) {
parser.addResult(combined);
parentDoclet.undocumented = doclet.undocumented = true;
parentDoclet.undocumented = eventDoclet.undocumented = true;
};
}
@ -460,7 +450,7 @@ function trackVars(parser, {enclosingScope}, {code, finishers}) {
doclet = parser._getDocletById(enclosingScopeId);
}
else {
doclet = parser._getDocletByLongname(jsdoc.name.LONGNAMES.GLOBAL);
doclet = parser._getDocletByLongname(LONGNAMES.GLOBAL);
}
if (doclet) {
@ -477,7 +467,7 @@ function makeSymbolFoundEvent(node, parser, filename) {
let parent;
const extras = {
code: jsdoc.src.astnode.getInfo(node)
code: astNode.getInfo(node)
};
switch (node.type) {
@ -487,7 +477,7 @@ function makeSymbolFoundEvent(node, parser, filename) {
trackVars(parser, node, e);
basename = jsdoc.name.getBasename(e.code.name);
basename = getBasename(e.code.name);
if (basename !== 'this') {
e.code.funcscope = parser.resolveVar(node, basename);
}
@ -498,7 +488,7 @@ function makeSymbolFoundEvent(node, parser, filename) {
case Syntax.AssignmentPattern:
parent = node.parent;
if ( node.leadingComments && parent && jsdoc.src.astnode.isFunction(parent) ) {
if ( node.leadingComments && parent && astNode.isFunction(parent) ) {
extras.finishers = [makeInlineParamsFinisher(parser)];
e = new SymbolFound(node, filename, extras);
@ -517,7 +507,7 @@ function makeSymbolFoundEvent(node, parser, filename) {
trackVars(parser, node, e);
basename = jsdoc.name.getBasename(e.code.name);
basename = getBasename(e.code.name);
break;
@ -588,7 +578,7 @@ function makeSymbolFoundEvent(node, parser, filename) {
trackVars(parser, node, e);
basename = jsdoc.name.getBasename(e.code.name);
basename = getBasename(e.code.name);
e.code.funcscope = parser.resolveVar(node, basename);
break;
@ -601,7 +591,7 @@ function makeSymbolFoundEvent(node, parser, filename) {
parent = node.parent;
// function parameters with inline comments
if ( node.leadingComments && parent && jsdoc.src.astnode.isFunction(parent) ) {
if ( node.leadingComments && parent && astNode.isFunction(parent) ) {
extras.finishers = [makeInlineParamsFinisher(parser)];
e = new SymbolFound(node, filename, extras);
@ -663,7 +653,7 @@ function makeSymbolFoundEvent(node, parser, filename) {
case Syntax.RestElement:
parent = node.parent;
if ( node.leadingComments && parent && jsdoc.src.astnode.isFunction(parent) ) {
if ( node.leadingComments && parent && astNode.isFunction(parent) ) {
extras.finishers = [makeInlineParamsFinisher(parser)];
e = new SymbolFound(node, filename, extras);
@ -689,7 +679,7 @@ function makeSymbolFoundEvent(node, parser, filename) {
trackVars(parser, node, e);
basename = jsdoc.name.getBasename(e.code.name);
basename = getBasename(e.code.name);
// auto-detect constants
if (node.parent.kind === 'const') {
e.code.kind = 'constant';

2
lib/jsdoc/src/walker.js
View File

@ -5,7 +5,7 @@
*/
const astnode = require('jsdoc/src/astnode');
const logger = require('jsdoc/util/logger');
const Syntax = require('jsdoc/src/syntax').Syntax;
const { Syntax } = require('jsdoc/src/syntax');
// TODO: docs
function getCurrentScope(scopes) {

54
lib/jsdoc/tag.js
View File

@ -9,18 +9,14 @@
* @requires module:jsdoc/util/logger
* @requires module:util
*/
const jsdoc = {
env: require('jsdoc/env'),
tag: {
dictionary: require('jsdoc/tag/dictionary'),
validator: require('jsdoc/tag/validator'),
type: require('jsdoc/tag/type')
},
util: {
logger: require('jsdoc/util/logger')
}
};
const env = require('jsdoc/env');
const logger = require('jsdoc/util/logger');
const path = require('jsdoc/path');
const tag = {
dictionary: require('jsdoc/tag/dictionary'),
validator: require('jsdoc/tag/validator'),
type: require('jsdoc/tag/type')
};
// Check whether the text is the same as a symbol name with leading or trailing whitespace. If so,
// the whitespace must be preserved, and the text cannot be trimmed.
@ -59,17 +55,17 @@ function addHiddenProperty(obj, propName, propValue) {
Object.defineProperty(obj, propName, {
value: propValue,
writable: true,
enumerable: Boolean(jsdoc.env.opts.debug),
enumerable: Boolean(env.opts.debug),
configurable: true
});
}
function parseType({text, originalTitle}, {canHaveName, canHaveType}, meta) {
try {
return jsdoc.tag.type.parse(text, canHaveName, canHaveType);
return tag.type.parse(text, canHaveName, canHaveType);
}
catch (e) {
jsdoc.util.logger.error(
logger.error(
'Unable to parse a tag\'s type expression%s with tag title "%s" and text "%s": %s',
meta.filename ? ( ` for source file ${path.join(meta.path, meta.filename)}${meta.lineno ? (` in line ${meta.lineno}`) : ''}` ) : '',
originalTitle,
@ -81,48 +77,50 @@ function parseType({text, originalTitle}, {canHaveName, canHaveType}, meta) {
}
}
function processTagText(tag, tagDef, meta) {
function processTagText(tagInstance, tagDef, meta) {
let tagType;
if (tagDef.onTagText) {
tag.text = tagDef.onTagText(tag.text);
tagInstance.text = tagDef.onTagText(tagInstance.text);
}
if (tagDef.canHaveType || tagDef.canHaveName) {
/** The value property represents the result of parsing the tag text. */
tag.value = {};
tagInstance.value = {};
tagType = parseType(tag, tagDef, meta);
tagType = parseType(tagInstance, tagDef, meta);
// It is possible for a tag to *not* have a type but still have
// optional or defaultvalue, e.g. '@param [foo]'.
// Although tagType.type.length == 0 we should still copy the other properties.
if (tagType.type) {
if (tagType.type.length) {
tag.value.type = {
tagInstance.value.type = {
names: tagType.type
};
addHiddenProperty(tag.value.type, 'parsedType', tagType.parsedType);
addHiddenProperty(tagInstance.value.type, 'parsedType', tagType.parsedType);
}
['optional', 'nullable', 'variable', 'defaultvalue'].forEach(prop => {
if (typeof tagType[prop] !== 'undefined') {
tag.value[prop] = tagType[prop];
tagInstance.value[prop] = tagType[prop];
}
});
}
if (tagType.text && tagType.text.length) {
tag.value.description = tagType.text;
tagInstance.value.description = tagType.text;
}
if (tagDef.canHaveName) {
// note the dash is a special case: as a param name it means "no name"
if (tagType.name && tagType.name !== '-') { tag.value.name = tagType.name; }
if (tagType.name && tagType.name !== '-') {
tagInstance.value.name = tagType.name;
}
}
}
else {
tag.value = tag.text;
tagInstance.value = tagInstance.text;
}
}
@ -136,7 +134,7 @@ function processTagText(tag, tagDef, meta) {
* @param {module:jsdoc/tag/dictionary.Dictionary} dict - The new tag dictionary.
*/
exports._replaceDictionary = function _replaceDictionary(dict) {
jsdoc.tag.dictionary = dict;
tag.dictionary = dict;
};
/**
@ -159,9 +157,9 @@ class Tag {
this.originalTitle = trim(tagTitle);
/** The title of the tag (for example, `title` in `@title text`). */
this.title = jsdoc.tag.dictionary.normalise(this.originalTitle);
this.title = tag.dictionary.normalize(this.originalTitle);
tagDef = jsdoc.tag.dictionary.lookUp(this.title);
tagDef = tag.dictionary.lookUp(this.title);
trimOpts = {
keepsWhitespace: tagDef.keepsWhitespace,
removesIndent: tagDef.removesIndent
@ -191,7 +189,7 @@ class Tag {
processTagText(this, tagDef, meta);
}
jsdoc.tag.validator.validate(this, tagDef, meta);
tag.validator.validate(this, tagDef, meta);
}
}
exports.Tag = Tag;

76
lib/jsdoc/tag/dictionary/definitions.js
View File

@ -3,23 +3,15 @@
* @module jsdoc/tag/dictionary/definitions
*/
const _ = require('lodash');
const jsdoc = {
env: require('jsdoc/env'),
name: require('jsdoc/name'),
src: {
astnode: require('jsdoc/src/astnode')
},
tag: {
inline: require('jsdoc/tag/inline'),
type: require('jsdoc/tag/type')
},
util: {
doop: require('jsdoc/util/doop'),
logger: require('jsdoc/util/logger')
}
};
const doop = require('jsdoc/util/doop');
const env = require('jsdoc/env');
const { isInlineTag } = require('jsdoc/tag/inline');
const logger = require('jsdoc/util/logger');
const name = require('jsdoc/name');
const { nodeToValue } = require('jsdoc/src/astnode');
const path = require('jsdoc/path');
const Syntax = require('jsdoc/src/syntax').Syntax;
const { Syntax } = require('jsdoc/src/syntax');
const parseTagType = require('jsdoc/tag/type').parse;
const hasOwnProp = Object.prototype.hasOwnProperty;
@ -31,7 +23,7 @@ const MODULE_NAMESPACE = 'module:';
// Clone a tag definition, excluding synonyms.
function cloneTagDef(tagDef, extras) {
const newTagDef = jsdoc.util.doop(tagDef);
const newTagDef = doop(tagDef);
delete newTagDef.synonyms;
@ -39,11 +31,11 @@ function cloneTagDef(tagDef, extras) {
}
function getSourcePaths() {
const sourcePaths = jsdoc.env.sourceFiles.slice(0) || [];
const sourcePaths = env.sourceFiles.slice(0) || [];
if (jsdoc.env.opts._) {
jsdoc.env.opts._.forEach(sourcePath => {
const resolved = path.resolve(jsdoc.env.pwd, sourcePath);
if (env.opts._) {
env.opts._.forEach(sourcePath => {
const resolved = path.resolve(env.pwd, sourcePath);
if (!sourcePaths.includes(resolved)) {
sourcePaths.push(resolved);
@ -83,7 +75,7 @@ function setDocletScopeToTitle(doclet, {title}) {
doclet.setScope(title);
}
catch (e) {
jsdoc.util.logger.error(e.message);
logger.error(e.message);
}
}
@ -121,11 +113,11 @@ function setDocletTypeToValueType(doclet, {value}) {
}
function setNameToFile(doclet) {
let name;
let docletName;
if (doclet.meta.filename) {
name = filepathMinusPrefix(doclet.meta.path) + doclet.meta.filename;
doclet.addTag('name', name);
docletName = filepathMinusPrefix(doclet.meta.path) + doclet.meta.filename;
doclet.addTag('name', docletName);
}
}
@ -137,30 +129,30 @@ function setDocletMemberof(doclet, {value}) {
function applyNamespace(docletOrNs, tag) {
if (typeof docletOrNs === 'string') { // ns
tag.value = jsdoc.name.applyNamespace(tag.value, docletOrNs);
tag.value = name.applyNamespace(tag.value, docletOrNs);
}
else { // doclet
if (!docletOrNs.name) {
return; // error?
}
docletOrNs.longname = jsdoc.name.applyNamespace(docletOrNs.name, tag.title);
docletOrNs.longname = name.applyNamespace(docletOrNs.name, tag.title);
}
}
function setDocletNameToFilename(doclet) {
let name = '';
let docletName = '';
if (doclet.meta.path) {
name = filepathMinusPrefix(doclet.meta.path);
docletName = filepathMinusPrefix(doclet.meta.path);
}
name += doclet.meta.filename.replace(/\.js$/i, '');
docletName += doclet.meta.filename.replace(/\.js$/i, '');
doclet.name = name;
doclet.name = docletName;
}
function parseTypeText(text) {
const tagType = jsdoc.tag.type.parse(text, false, true);
const tagType = parseTagType(text, false, true);
return tagType.typeExpression || text;
}
@ -187,8 +179,8 @@ function parseBorrows(doclet, {text}) {
}
}
function stripModuleNamespace(name) {
return name.replace(/^module:/, '');
function stripModuleNamespace(docletName) {
return docletName.replace(/^module:/, '');
}
function firstWordOf(string) {
@ -373,8 +365,6 @@ let baseTags = exports.baseTags = {
},
default: {
onTagged(doclet, {value}) {
const nodeToValue = jsdoc.src.astnode.nodeToValue;
if (value) {
doclet.defaultvalue = value;
}
@ -493,7 +483,7 @@ let baseTags = exports.baseTags = {
global: {
mustNotHaveValue: true,
onTagged(doclet) {
doclet.scope = jsdoc.name.SCOPE.NAMES.GLOBAL;
doclet.scope = name.SCOPE.NAMES.GLOBAL;
delete doclet.memberof;
}
},
@ -545,7 +535,7 @@ let baseTags = exports.baseTags = {
},
lends: {
onTagged(doclet, {value}) {
doclet.alias = value || jsdoc.name.LONGNAMES.GLOBAL;
doclet.alias = value || name.LONGNAMES.GLOBAL;
doclet.addTag('undocumented');
}
},
@ -578,7 +568,7 @@ let baseTags = exports.baseTags = {
onTagged(doclet, tag) {
if (tag.originalTitle === 'memberof!') {
doclet.forceMemberof = true;
if (tag.value === jsdoc.name.LONGNAMES.GLOBAL) {
if (tag.value === name.LONGNAMES.GLOBAL) {
doclet.addTag('global');
delete doclet.memberof;
}
@ -687,7 +677,7 @@ let baseTags = exports.baseTags = {
let requiresName;
// inline link tags are passed through as-is so that `@requires {@link foo}` works
if ( jsdoc.tag.inline.isInlineTag(value, 'link\\S*') ) {
if ( isInlineTag(value, 'link\\S*') ) {
requiresName = value;
}
// otherwise, assume it's a module
@ -1058,10 +1048,10 @@ exports.defineTags = (dictionary, tagDefinitions) => {
let dictionaries;
if (!tagDefinitions) {
dictionaries = jsdoc.env.conf.tags.dictionaries;
dictionaries = env.conf.tags.dictionaries;
if (!dictionaries) {
jsdoc.util.logger.error('The configuration setting "tags.dictionaries" is undefined. ' +
logger.error('The configuration setting "tags.dictionaries" is undefined. ' +
'Unable to load tag definitions.');
return;
@ -1074,7 +1064,7 @@ exports.defineTags = (dictionary, tagDefinitions) => {
const tagDefs = exports[DEFINITIONS[dictName]];
if (!tagDefs) {
jsdoc.util.logger.error('The configuration setting "tags.dictionaries" contains ' +
logger.error('The configuration setting "tags.dictionaries" contains ' +
'the unknown dictionary name %s. Ignoring the dictionary.', dictName);
return;

18
lib/jsdoc/tag/type.js
View File

@ -1,16 +1,10 @@
/**
* @module jsdoc/tag/type
*/
const { cast } = require('jsdoc/util/cast');
const catharsis = require('catharsis');
const jsdoc = {
name: require('jsdoc/name'),
tag: {
inline: require('jsdoc/tag/inline')
},
util: {
cast: require('jsdoc/util/cast')
}
};
const { extractInlineTag } = require('jsdoc/tag/inline');
const { splitName } = require('jsdoc/name');
/**
* Information about a type expression extracted from tag text.
@ -97,14 +91,14 @@ function getTagInfo(tagValue, canHaveName, canHaveType) {
}
if (canHaveName) {
nameAndDescription = jsdoc.name.splitName(text);
nameAndDescription = splitName(text);
name = nameAndDescription.name;
text = nameAndDescription.description;
}
// an inline @type tag, like {@type Foo}, overrides the type expression
if (canHaveType) {
typeOverride = jsdoc.tag.inline.extractInlineTag(text, 'type');
typeOverride = extractInlineTag(text, 'type');
if (typeOverride.tags && typeOverride.tags[0]) {
typeExpression = typeOverride.tags[0].text;
}
@ -160,7 +154,7 @@ function parseName(tagInfo) {
// like 'foo=bar' or 'foo = bar'
if ( /^(.+?)\s*=\s*(.+)$/.test(tagInfo.name) ) {
tagInfo.name = RegExp.$1;
tagInfo.defaultvalue = jsdoc.util.cast.cast(RegExp.$2);
tagInfo.defaultvalue = cast(RegExp.$2);
}
}

2
lib/jsdoc/util/logger.js
View File

@ -34,7 +34,7 @@
* @see http://nodejs.org/api/util.html#util_util_format_format
*/
const EventEmitter = require('events').EventEmitter;
const { EventEmitter } = require('events');
const util = require('util');
/* eslint-disable no-empty-function */

2
plugins/eventDumper.js
View File

@ -5,7 +5,7 @@
*/
const _ = require('lodash');
const doop = require('jsdoc/util/doop');
const dump = require('jsdoc/util/dumper').dump;
const { dump } = require('jsdoc/util/dumper');
const env = require('jsdoc/env');
const conf = env.conf.eventDumper || {};

2
templates/default/publish.js
View File

@ -4,7 +4,7 @@ const fs = require('jsdoc/fs');
const helper = require('jsdoc/util/templateHelper');
const logger = require('jsdoc/util/logger');
const path = require('jsdoc/path');
const taffy = require('taffydb').taffy;
const { taffy } = require('taffydb');
const template = require('jsdoc/template');
const htmlsafe = helper.htmlsafe;