|
|
/** * @fileoverview Validates JSDoc comments are syntactically correct * @author Nicholas C. Zakas */"use strict";
//------------------------------------------------------------------------------
// Requirements
//------------------------------------------------------------------------------
const doctrine = require("doctrine");
//------------------------------------------------------------------------------
// Rule Definition
//------------------------------------------------------------------------------
module.exports = { meta: { type: "suggestion",
docs: { description: "enforce valid JSDoc comments", category: "Possible Errors", recommended: false, url: "https://eslint.org/docs/rules/valid-jsdoc" },
schema: [ { type: "object", properties: { prefer: { type: "object", additionalProperties: { type: "string" } }, preferType: { type: "object", additionalProperties: { type: "string" } }, requireReturn: { type: "boolean", default: true }, requireParamDescription: { type: "boolean", default: true }, requireReturnDescription: { type: "boolean", default: true }, matchDescription: { type: "string" }, requireReturnType: { type: "boolean", default: true }, requireParamType: { type: "boolean", default: true } }, additionalProperties: false } ],
fixable: "code", messages: { unexpectedTag: "Unexpected @{{title}} tag; function has no return statement.", expected: "Expected JSDoc for '{{name}}' but found '{{jsdocName}}'.", use: "Use @{{name}} instead.", useType: "Use '{{expectedTypeName}}' instead of '{{currentTypeName}}'.", syntaxError: "JSDoc syntax error.", missingBrace: "JSDoc type missing brace.", missingParamDesc: "Missing JSDoc parameter description for '{{name}}'.", missingParamType: "Missing JSDoc parameter type for '{{name}}'.", missingReturnType: "Missing JSDoc return type.", missingReturnDesc: "Missing JSDoc return description.", missingReturn: "Missing JSDoc @{{returns}} for function.", missingParam: "Missing JSDoc for parameter '{{name}}'.", duplicateParam: "Duplicate JSDoc parameter '{{name}}'.", unsatisfiedDesc: "JSDoc description does not satisfy the regex pattern." },
deprecated: true, replacedBy: [] },
create(context) {
const options = context.options[0] || {}, prefer = options.prefer || {}, sourceCode = context.getSourceCode(),
// these both default to true, so you have to explicitly make them false
requireReturn = options.requireReturn !== false, requireParamDescription = options.requireParamDescription !== false, requireReturnDescription = options.requireReturnDescription !== false, requireReturnType = options.requireReturnType !== false, requireParamType = options.requireParamType !== false, preferType = options.preferType || {}, checkPreferType = Object.keys(preferType).length !== 0;
//--------------------------------------------------------------------------
// Helpers
//--------------------------------------------------------------------------
// Using a stack to store if a function returns or not (handling nested functions)
const fns = [];
/** * Check if node type is a Class * @param {ASTNode} node node to check. * @returns {boolean} True is its a class * @private */ function isTypeClass(node) { return node.type === "ClassExpression" || node.type === "ClassDeclaration"; }
/** * When parsing a new function, store it in our function stack. * @param {ASTNode} node A function node to check. * @returns {void} * @private */ function startFunction(node) { fns.push({ returnPresent: (node.type === "ArrowFunctionExpression" && node.body.type !== "BlockStatement") || isTypeClass(node) || node.async }); }
/** * Indicate that return has been found in the current function. * @param {ASTNode} node The return node. * @returns {void} * @private */ function addReturn(node) { const functionState = fns[fns.length - 1];
if (functionState && node.argument !== null) { functionState.returnPresent = true; } }
/** * Check if return tag type is void or undefined * @param {Object} tag JSDoc tag * @returns {boolean} True if its of type void or undefined * @private */ function isValidReturnType(tag) { return tag.type === null || tag.type.name === "void" || tag.type.type === "UndefinedLiteral"; }
/** * Check if type should be validated based on some exceptions * @param {Object} type JSDoc tag * @returns {boolean} True if it can be validated * @private */ function canTypeBeValidated(type) { return type !== "UndefinedLiteral" && // {undefined} as there is no name property available.
type !== "NullLiteral" && // {null}
type !== "NullableLiteral" && // {?}
type !== "FunctionType" && // {function(a)}
type !== "AllLiteral"; // {*}
}
/** * Extract the current and expected type based on the input type object * @param {Object} type JSDoc tag * @returns {{currentType: Doctrine.Type, expectedTypeName: string}} The current type annotation and * the expected name of the annotation * @private */ function getCurrentExpectedTypes(type) { let currentType;
if (type.name) { currentType = type; } else if (type.expression) { currentType = type.expression; }
return { currentType, expectedTypeName: currentType && preferType[currentType.name] }; }
/** * Gets the location of a JSDoc node in a file * @param {Token} jsdocComment The comment that this node is parsed from * @param {{range: number[]}} parsedJsdocNode A tag or other node which was parsed from this comment * @returns {{start: SourceLocation, end: SourceLocation}} The 0-based source location for the tag */ function getAbsoluteRange(jsdocComment, parsedJsdocNode) { return { start: sourceCode.getLocFromIndex(jsdocComment.range[0] + 2 + parsedJsdocNode.range[0]), end: sourceCode.getLocFromIndex(jsdocComment.range[0] + 2 + parsedJsdocNode.range[1]) }; }
/** * Validate type for a given JSDoc node * @param {Object} jsdocNode JSDoc node * @param {Object} type JSDoc tag * @returns {void} * @private */ function validateType(jsdocNode, type) { if (!type || !canTypeBeValidated(type.type)) { return; }
const typesToCheck = []; let elements = [];
switch (type.type) { case "TypeApplication": // {Array.<String>}
elements = type.applications[0].type === "UnionType" ? type.applications[0].elements : type.applications; typesToCheck.push(getCurrentExpectedTypes(type)); break; case "RecordType": // {{20:String}}
elements = type.fields; break; case "UnionType": // {String|number|Test}
case "ArrayType": // {[String, number, Test]}
elements = type.elements; break; case "FieldType": // Array.<{count: number, votes: number}>
if (type.value) { typesToCheck.push(getCurrentExpectedTypes(type.value)); } break; default: typesToCheck.push(getCurrentExpectedTypes(type)); }
elements.forEach(validateType.bind(null, jsdocNode));
typesToCheck.forEach(typeToCheck => { if (typeToCheck.expectedTypeName && typeToCheck.expectedTypeName !== typeToCheck.currentType.name) { context.report({ node: jsdocNode, messageId: "useType", loc: getAbsoluteRange(jsdocNode, typeToCheck.currentType), data: { currentTypeName: typeToCheck.currentType.name, expectedTypeName: typeToCheck.expectedTypeName }, fix(fixer) { return fixer.replaceTextRange( typeToCheck.currentType.range.map(indexInComment => jsdocNode.range[0] + 2 + indexInComment), typeToCheck.expectedTypeName ); } }); } }); }
/** * Validate the JSDoc node and output warnings if anything is wrong. * @param {ASTNode} node The AST node to check. * @returns {void} * @private */ function checkJSDoc(node) { const jsdocNode = sourceCode.getJSDocComment(node), functionData = fns.pop(), paramTagsByName = Object.create(null), paramTags = []; let hasReturns = false, returnsTag, hasConstructor = false, isInterface = false, isOverride = false, isAbstract = false;
// make sure only to validate JSDoc comments
if (jsdocNode) { let jsdoc;
try { jsdoc = doctrine.parse(jsdocNode.value, { strict: true, unwrap: true, sloppy: true, range: true }); } catch (ex) {
if (/braces/iu.test(ex.message)) { context.report({ node: jsdocNode, messageId: "missingBrace" }); } else { context.report({ node: jsdocNode, messageId: "syntaxError" }); }
return; }
jsdoc.tags.forEach(tag => {
switch (tag.title.toLowerCase()) {
case "param": case "arg": case "argument": paramTags.push(tag); break;
case "return": case "returns": hasReturns = true; returnsTag = tag; break;
case "constructor": case "class": hasConstructor = true; break;
case "override": case "inheritdoc": isOverride = true; break;
case "abstract": case "virtual": isAbstract = true; break;
case "interface": isInterface = true; break;
// no default
}
// check tag preferences
if (Object.prototype.hasOwnProperty.call(prefer, tag.title) && tag.title !== prefer[tag.title]) { const entireTagRange = getAbsoluteRange(jsdocNode, tag);
context.report({ node: jsdocNode, messageId: "use", loc: { start: entireTagRange.start, end: { line: entireTagRange.start.line, column: entireTagRange.start.column + `@${tag.title}`.length } }, data: { name: prefer[tag.title] }, fix(fixer) { return fixer.replaceTextRange( [ jsdocNode.range[0] + tag.range[0] + 3, jsdocNode.range[0] + tag.range[0] + tag.title.length + 3 ], prefer[tag.title] ); } }); }
// validate the types
if (checkPreferType && tag.type) { validateType(jsdocNode, tag.type); } });
paramTags.forEach(param => { if (requireParamType && !param.type) { context.report({ node: jsdocNode, messageId: "missingParamType", loc: getAbsoluteRange(jsdocNode, param), data: { name: param.name } }); } if (!param.description && requireParamDescription) { context.report({ node: jsdocNode, messageId: "missingParamDesc", loc: getAbsoluteRange(jsdocNode, param), data: { name: param.name } }); } if (paramTagsByName[param.name]) { context.report({ node: jsdocNode, messageId: "duplicateParam", loc: getAbsoluteRange(jsdocNode, param), data: { name: param.name } }); } else if (param.name.indexOf(".") === -1) { paramTagsByName[param.name] = param; } });
if (hasReturns) { if (!requireReturn && !functionData.returnPresent && (returnsTag.type === null || !isValidReturnType(returnsTag)) && !isAbstract) { context.report({ node: jsdocNode, messageId: "unexpectedTag", loc: getAbsoluteRange(jsdocNode, returnsTag), data: { title: returnsTag.title } }); } else { if (requireReturnType && !returnsTag.type) { context.report({ node: jsdocNode, messageId: "missingReturnType" }); }
if (!isValidReturnType(returnsTag) && !returnsTag.description && requireReturnDescription) { context.report({ node: jsdocNode, messageId: "missingReturnDesc" }); } } }
// check for functions missing @returns
if (!isOverride && !hasReturns && !hasConstructor && !isInterface && node.parent.kind !== "get" && node.parent.kind !== "constructor" && node.parent.kind !== "set" && !isTypeClass(node)) { if (requireReturn || (functionData.returnPresent && !node.async)) { context.report({ node: jsdocNode, messageId: "missingReturn", data: { returns: prefer.returns || "returns" } }); } }
// check the parameters
const jsdocParamNames = Object.keys(paramTagsByName);
if (node.params) { node.params.forEach((param, paramsIndex) => { const bindingParam = param.type === "AssignmentPattern" ? param.left : param;
// TODO(nzakas): Figure out logical things to do with destructured, default, rest params
if (bindingParam.type === "Identifier") { const name = bindingParam.name;
if (jsdocParamNames[paramsIndex] && (name !== jsdocParamNames[paramsIndex])) { context.report({ node: jsdocNode, messageId: "expected", loc: getAbsoluteRange(jsdocNode, paramTagsByName[jsdocParamNames[paramsIndex]]), data: { name, jsdocName: jsdocParamNames[paramsIndex] } }); } else if (!paramTagsByName[name] && !isOverride) { context.report({ node: jsdocNode, messageId: "missingParam", data: { name } }); } } }); }
if (options.matchDescription) { const regex = new RegExp(options.matchDescription, "u");
if (!regex.test(jsdoc.description)) { context.report({ node: jsdocNode, messageId: "unsatisfiedDesc" }); } }
}
}
//--------------------------------------------------------------------------
// Public
//--------------------------------------------------------------------------
return { ArrowFunctionExpression: startFunction, FunctionExpression: startFunction, FunctionDeclaration: startFunction, ClassExpression: startFunction, ClassDeclaration: startFunction, "ArrowFunctionExpression:exit": checkJSDoc, "FunctionExpression:exit": checkJSDoc, "FunctionDeclaration:exit": checkJSDoc, "ClassExpression:exit": checkJSDoc, "ClassDeclaration:exit": checkJSDoc, ReturnStatement: addReturn };
}};
|
