--- /dev/null
+/**
+ * @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
+ };
+
+ }
+};
projects / dotfiles / .git / blobdiff