| /** |
| * @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 |
| }; |
| |
| } |
| }; |
