diff options
Diffstat (limited to 'node_modules/tslint/lib/rules/completedDocsRule.js')
| -rw-r--r-- | node_modules/tslint/lib/rules/completedDocsRule.js | 259 |
1 files changed, 123 insertions, 136 deletions
diff --git a/node_modules/tslint/lib/rules/completedDocsRule.js b/node_modules/tslint/lib/rules/completedDocsRule.js index d64315563..9333c44ac 100644 --- a/node_modules/tslint/lib/rules/completedDocsRule.js +++ b/node_modules/tslint/lib/rules/completedDocsRule.js @@ -17,7 +17,7 @@ */ Object.defineProperty(exports, "__esModule", { value: true }); var tslib_1 = require("tslib"); -var tsutils_1 = require("tsutils"); +var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q; var ts = require("typescript"); var Lint = require("../index"); var exclusionFactory_1 = require("./completed-docs/exclusionFactory"); @@ -42,7 +42,7 @@ exports.PRIVACY_PRIVATE = "private"; exports.PRIVACY_PROTECTED = "protected"; exports.PRIVACY_PUBLIC = "public"; exports.TAGS_FOR_CONTENT = "content"; -exports.TAGS_FOR_EXISTENCE = "exists"; +exports.TAGS_FOR_EXISTENCE = "existence"; exports.VISIBILITY_EXPORTED = "exported"; exports.VISIBILITY_INTERNAL = "internal"; var Rule = /** @class */ (function (_super) { @@ -55,9 +55,8 @@ var Rule = /** @class */ (function (_super) { } Rule.prototype.applyWithProgram = function (sourceFile, program) { var options = this.getOptions(); - var completedDocsWalker = new CompletedDocsWalker(sourceFile, options, program); - completedDocsWalker.setExclusionsMap(this.getExclusionsMap(options.ruleArguments)); - return this.applyWithWalker(completedDocsWalker); + var exclusionsMap = this.getExclusionsMap(options.ruleArguments); + return this.applyWithFunction(sourceFile, walk, exclusionsMap, program.getTypeChecker()); }; Rule.prototype.getExclusionsMap = function (ruleArguments) { if (ruleArguments.length === 0) { @@ -162,8 +161,8 @@ var Rule = /** @class */ (function (_super) { /* tslint:disable:object-literal-sort-keys */ Rule.metadata = { ruleName: "completed-docs", - description: "Enforces documentation for important items be filled out.", - optionsDescription: (_k = ["\n `true` to enable for [", "]],\n or an array with each item in one of two formats:\n\n * `string` to enable for that type\n * `object` keying types to when their documentation is required:\n * `\"", "\"` and `\"", "\"` may specify:\n * `\"", "\"`:\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`:\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * Other types may specify `\"", "\"`:\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * All types may also provide `\"", "\"`\n with members specifying tags that allow the docs to not have a body.\n * `\"", "\"`: Object mapping tags to `RegExp` bodies content allowed to count as complete docs.\n * `\"", "\"`: Array of tags that must only exist to count as complete docs.\n\n Types that may be enabled are:\n\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`"], _k.raw = ["\n \\`true\\` to enable for [", "]],\n or an array with each item in one of two formats:\n\n * \\`string\\` to enable for that type\n * \\`object\\` keying types to when their documentation is required:\n * \\`\"", "\"\\` and \\`\"", "\"\\` may specify:\n * \\`\"", "\"\\`:\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`:\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * Other types may specify \\`\"", "\"\\`:\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * All types may also provide \\`\"", "\"\\`\n with members specifying tags that allow the docs to not have a body.\n * \\`\"", "\"\\`: Object mapping tags to \\`RegExp\\` bodies content allowed to count as complete docs.\n * \\`\"", "\"\\`: Array of tags that must only exist to count as complete docs.\n\n Types that may be enabled are:\n\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`"], Lint.Utils.dedent(_k, Object.keys(Rule.defaultArguments).join(", "), exports.ARGUMENT_METHODS, exports.ARGUMENT_PROPERTIES, exports.DESCRIPTOR_PRIVACIES, exports.ALL, exports.PRIVACY_PRIVATE, exports.PRIVACY_PROTECTED, exports.PRIVACY_PUBLIC, exports.DESCRIPTOR_LOCATIONS, exports.ALL, exports.LOCATION_INSTANCE, exports.LOCATION_STATIC, exports.DESCRIPTOR_VISIBILITIES, exports.ALL, exports.VISIBILITY_EXPORTED, exports.VISIBILITY_INTERNAL, exports.DESCRIPTOR_TAGS, exports.TAGS_FOR_CONTENT, exports.TAGS_FOR_EXISTENCE, exports.ARGUMENT_CLASSES, exports.ARGUMENT_ENUMS, exports.ARGUMENT_ENUM_MEMBERS, exports.ARGUMENT_FUNCTIONS, exports.ARGUMENT_INTERFACES, exports.ARGUMENT_METHODS, exports.ARGUMENT_NAMESPACES, exports.ARGUMENT_PROPERTIES, exports.ARGUMENT_TYPES, exports.ARGUMENT_VARIABLES)), + description: "Enforces JSDoc comments for important items be filled out.", + optionsDescription: Lint.Utils.dedent(templateObject_1 || (templateObject_1 = tslib_1.__makeTemplateObject(["\n `true` to enable for `[", "]`,\n or an array with each item in one of two formats:\n\n * `string` to enable for that type\n * `object` keying types to when their documentation is required:\n * `\"", "\"` and `\"", "\"` may specify:\n * `\"", "\"`:\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`:\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * Other types may specify `\"", "\"`:\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * All types may also provide `\"", "\"`\n with members specifying tags that allow the docs to not have a body.\n * `\"", "\"`: Object mapping tags to `RegExp` bodies content allowed to count as complete docs.\n * `\"", "\"`: Array of tags that must only exist to count as complete docs.\n\n Types that may be enabled are:\n\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`\n * `\"", "\"`"], ["\n \\`true\\` to enable for \\`[", "]\\`,\n or an array with each item in one of two formats:\n\n * \\`string\\` to enable for that type\n * \\`object\\` keying types to when their documentation is required:\n * \\`\"", "\"\\` and \\`\"", "\"\\` may specify:\n * \\`\"", "\"\\`:\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`:\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * Other types may specify \\`\"", "\"\\`:\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * All types may also provide \\`\"", "\"\\`\n with members specifying tags that allow the docs to not have a body.\n * \\`\"", "\"\\`: Object mapping tags to \\`RegExp\\` bodies content allowed to count as complete docs.\n * \\`\"", "\"\\`: Array of tags that must only exist to count as complete docs.\n\n Types that may be enabled are:\n\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`\n * \\`\"", "\"\\`"])), Object.keys(Rule.defaultArguments).join(", "), exports.ARGUMENT_METHODS, exports.ARGUMENT_PROPERTIES, exports.DESCRIPTOR_PRIVACIES, exports.ALL, exports.PRIVACY_PRIVATE, exports.PRIVACY_PROTECTED, exports.PRIVACY_PUBLIC, exports.DESCRIPTOR_LOCATIONS, exports.ALL, exports.LOCATION_INSTANCE, exports.LOCATION_STATIC, exports.DESCRIPTOR_VISIBILITIES, exports.ALL, exports.VISIBILITY_EXPORTED, exports.VISIBILITY_INTERNAL, exports.DESCRIPTOR_TAGS, exports.TAGS_FOR_CONTENT, exports.TAGS_FOR_EXISTENCE, exports.ARGUMENT_CLASSES, exports.ARGUMENT_ENUMS, exports.ARGUMENT_ENUM_MEMBERS, exports.ARGUMENT_FUNCTIONS, exports.ARGUMENT_INTERFACES, exports.ARGUMENT_METHODS, exports.ARGUMENT_NAMESPACES, exports.ARGUMENT_PROPERTIES, exports.ARGUMENT_TYPES, exports.ARGUMENT_VARIABLES), options: { type: "array", items: { @@ -184,18 +183,18 @@ var Rule = /** @class */ (function (_super) { }, { type: "object", - properties: (_l = {}, - _l[exports.ARGUMENT_CLASSES] = Rule.ARGUMENT_DESCRIPTOR_BLOCK, - _l[exports.ARGUMENT_ENUMS] = Rule.ARGUMENT_DESCRIPTOR_BLOCK, - _l[exports.ARGUMENT_ENUM_MEMBERS] = Rule.ARGUMENT_DESCRIPTOR_BLOCK, - _l[exports.ARGUMENT_FUNCTIONS] = Rule.ARGUMENT_DESCRIPTOR_BLOCK, - _l[exports.ARGUMENT_INTERFACES] = Rule.ARGUMENT_DESCRIPTOR_BLOCK, - _l[exports.ARGUMENT_METHODS] = Rule.ARGUMENT_DESCRIPTOR_CLASS, - _l[exports.ARGUMENT_NAMESPACES] = Rule.ARGUMENT_DESCRIPTOR_BLOCK, - _l[exports.ARGUMENT_PROPERTIES] = Rule.ARGUMENT_DESCRIPTOR_CLASS, - _l[exports.ARGUMENT_TYPES] = Rule.ARGUMENT_DESCRIPTOR_BLOCK, - _l[exports.ARGUMENT_VARIABLES] = Rule.ARGUMENT_DESCRIPTOR_BLOCK, - _l), + properties: (_k = {}, + _k[exports.ARGUMENT_CLASSES] = Rule.ARGUMENT_DESCRIPTOR_BLOCK, + _k[exports.ARGUMENT_ENUMS] = Rule.ARGUMENT_DESCRIPTOR_BLOCK, + _k[exports.ARGUMENT_ENUM_MEMBERS] = Rule.ARGUMENT_DESCRIPTOR_BLOCK, + _k[exports.ARGUMENT_FUNCTIONS] = Rule.ARGUMENT_DESCRIPTOR_BLOCK, + _k[exports.ARGUMENT_INTERFACES] = Rule.ARGUMENT_DESCRIPTOR_BLOCK, + _k[exports.ARGUMENT_METHODS] = Rule.ARGUMENT_DESCRIPTOR_CLASS, + _k[exports.ARGUMENT_NAMESPACES] = Rule.ARGUMENT_DESCRIPTOR_BLOCK, + _k[exports.ARGUMENT_PROPERTIES] = Rule.ARGUMENT_DESCRIPTOR_CLASS, + _k[exports.ARGUMENT_TYPES] = Rule.ARGUMENT_DESCRIPTOR_BLOCK, + _k[exports.ARGUMENT_VARIABLES] = Rule.ARGUMENT_DESCRIPTOR_BLOCK, + _k), }, ], }, @@ -205,24 +204,27 @@ var Rule = /** @class */ (function (_super) { [true, exports.ARGUMENT_ENUMS, exports.ARGUMENT_FUNCTIONS, exports.ARGUMENT_METHODS], [ true, - (_m = {}, - _m[exports.ARGUMENT_ENUMS] = true, - _m[exports.ARGUMENT_FUNCTIONS] = (_o = {}, - _o[exports.DESCRIPTOR_VISIBILITIES] = [exports.VISIBILITY_EXPORTED], + (_l = {}, + _l[exports.ARGUMENT_ENUMS] = true, + _l[exports.ARGUMENT_FUNCTIONS] = (_m = {}, + _m[exports.DESCRIPTOR_VISIBILITIES] = [exports.VISIBILITY_EXPORTED], + _m), + _l[exports.ARGUMENT_METHODS] = (_o = {}, + _o[exports.DESCRIPTOR_LOCATIONS] = exports.LOCATION_INSTANCE, + _o[exports.DESCRIPTOR_PRIVACIES] = [exports.PRIVACY_PUBLIC, exports.PRIVACY_PROTECTED], _o), - _m[exports.ARGUMENT_METHODS] = (_p = {}, - _p[exports.DESCRIPTOR_LOCATIONS] = exports.LOCATION_INSTANCE, - _p[exports.DESCRIPTOR_PRIVACIES] = [exports.PRIVACY_PUBLIC, exports.PRIVACY_PROTECTED], + _l[exports.ARGUMENT_PROPERTIES] = (_p = {}, + _p[exports.DESCRIPTOR_TAGS] = (_q = {}, + _q[exports.TAGS_FOR_CONTENT] = { + see: ["#.*"], + }, + _q[exports.TAGS_FOR_EXISTENCE] = ["inheritdoc"], + _q), _p), - _m[exports.DESCRIPTOR_TAGS] = (_q = {}, - _q[exports.TAGS_FOR_CONTENT] = { - see: ["#.*"], - }, - _q[exports.TAGS_FOR_EXISTENCE] = ["inheritdoc"], - _q), - _m), + _l), ], ], + rationale: Lint.Utils.dedent(templateObject_2 || (templateObject_2 = tslib_1.__makeTemplateObject(["\n Helps ensure important components are documented.\n\n Note: use this rule sparingly. It's better to have self-documenting names on components with single, consice responsibilities.\n Comments that only restate the names of variables add nothing to code, and can easily become outdated.\n "], ["\n Helps ensure important components are documented.\n\n Note: use this rule sparingly. It's better to have self-documenting names on components with single, consice responsibilities.\n Comments that only restate the names of variables add nothing to code, and can easily become outdated.\n "]))), type: "style", typescriptOnly: false, requiresTypeInfo: true, @@ -230,63 +232,72 @@ var Rule = /** @class */ (function (_super) { return Rule; }(Lint.Rules.TypedRule)); exports.Rule = Rule; -var CompletedDocsWalker = /** @class */ (function (_super) { - tslib_1.__extends(CompletedDocsWalker, _super); - function CompletedDocsWalker() { - return _super !== null && _super.apply(this, arguments) || this; +var modifierAliases = { + export: "exported", +}; +function walk(context, typeChecker) { + return ts.forEachChild(context.sourceFile, cb); + function cb(node) { + switch (node.kind) { + case ts.SyntaxKind.ClassDeclaration: + checkNode(node, exports.ARGUMENT_CLASSES); + break; + case ts.SyntaxKind.EnumDeclaration: + checkNode(node, exports.ARGUMENT_ENUMS); + for (var _i = 0, _a = node.members; _i < _a.length; _i++) { + var member = _a[_i]; + // Enum members don't have modifiers, so use the parent + // enum declaration when checking the requirements. + checkNode(member, exports.ARGUMENT_ENUM_MEMBERS, node); + } + break; + case ts.SyntaxKind.FunctionDeclaration: + checkNode(node, exports.ARGUMENT_FUNCTIONS); + break; + case ts.SyntaxKind.InterfaceDeclaration: + checkNode(node, exports.ARGUMENT_INTERFACES); + break; + case ts.SyntaxKind.MethodDeclaration: + if (node.parent.kind !== ts.SyntaxKind.ObjectLiteralExpression) { + checkNode(node, exports.ARGUMENT_METHODS); + } + break; + case ts.SyntaxKind.ModuleDeclaration: + checkNode(node, exports.ARGUMENT_NAMESPACES); + break; + case ts.SyntaxKind.PropertyDeclaration: + checkNode(node, exports.ARGUMENT_PROPERTIES); + break; + case ts.SyntaxKind.TypeAliasDeclaration: + checkNode(node, exports.ARGUMENT_TYPES); + break; + case ts.SyntaxKind.VariableStatement: + // Only check variables at the namespace/module-level or file-level + // and not variables declared inside functions and other things. + switch (node.parent.kind) { + case ts.SyntaxKind.SourceFile: + case ts.SyntaxKind.ModuleBlock: + for (var _b = 0, _c = node.declarationList.declarations; _b < _c.length; _b++) { + var declaration = _c[_b]; + checkNode(declaration, exports.ARGUMENT_VARIABLES, node); + } + } + break; + case ts.SyntaxKind.GetAccessor: + case ts.SyntaxKind.SetAccessor: + if (node.parent.kind !== ts.SyntaxKind.ObjectLiteralExpression) { + checkNode(node, exports.ARGUMENT_PROPERTIES); + } + } + return ts.forEachChild(node, cb); } - CompletedDocsWalker.prototype.setExclusionsMap = function (exclusionsMap) { - this.exclusionsMap = exclusionsMap; - }; - CompletedDocsWalker.prototype.visitClassDeclaration = function (node) { - this.checkNode(node, exports.ARGUMENT_CLASSES); - _super.prototype.visitClassDeclaration.call(this, node); - }; - CompletedDocsWalker.prototype.visitEnumDeclaration = function (node) { - this.checkNode(node, exports.ARGUMENT_ENUMS); - _super.prototype.visitEnumDeclaration.call(this, node); - }; - CompletedDocsWalker.prototype.visitEnumMember = function (node) { - // Enum members don't have modifiers, so use the parent - // enum declaration when checking the requirements. - this.checkNode(node, exports.ARGUMENT_ENUM_MEMBERS, node.parent); - _super.prototype.visitEnumMember.call(this, node); - }; - CompletedDocsWalker.prototype.visitFunctionDeclaration = function (node) { - this.checkNode(node, exports.ARGUMENT_FUNCTIONS); - _super.prototype.visitFunctionDeclaration.call(this, node); - }; - CompletedDocsWalker.prototype.visitInterfaceDeclaration = function (node) { - this.checkNode(node, exports.ARGUMENT_INTERFACES); - _super.prototype.visitInterfaceDeclaration.call(this, node); - }; - CompletedDocsWalker.prototype.visitMethodDeclaration = function (node) { - this.checkNode(node, exports.ARGUMENT_METHODS); - _super.prototype.visitMethodDeclaration.call(this, node); - }; - CompletedDocsWalker.prototype.visitModuleDeclaration = function (node) { - this.checkNode(node, exports.ARGUMENT_NAMESPACES); - _super.prototype.visitModuleDeclaration.call(this, node); - }; - CompletedDocsWalker.prototype.visitPropertyDeclaration = function (node) { - this.checkNode(node, exports.ARGUMENT_PROPERTIES); - _super.prototype.visitPropertyDeclaration.call(this, node); - }; - CompletedDocsWalker.prototype.visitTypeAliasDeclaration = function (node) { - this.checkNode(node, exports.ARGUMENT_TYPES); - _super.prototype.visitTypeAliasDeclaration.call(this, node); - }; - CompletedDocsWalker.prototype.visitVariableDeclaration = function (node) { - this.checkVariable(node); - _super.prototype.visitVariableDeclaration.call(this, node); - }; - CompletedDocsWalker.prototype.checkNode = function (node, nodeType, requirementNode) { + function checkNode(node, nodeType, requirementNode) { if (requirementNode === void 0) { requirementNode = node; } var name = node.name; if (name === undefined) { return; } - var exclusions = this.exclusionsMap.get(nodeType); + var exclusions = context.options.get(nodeType); if (exclusions === undefined) { return; } @@ -296,62 +307,38 @@ var CompletedDocsWalker = /** @class */ (function (_super) { return; } } - var symbol = this.getTypeChecker().getSymbolAtLocation(name); + var symbol = typeChecker.getSymbolAtLocation(name); if (symbol === undefined) { return; } - var comments = symbol.getDocumentationComment(); - this.checkComments(node, this.describeNode(nodeType), comments, requirementNode); - }; - CompletedDocsWalker.prototype.checkVariable = function (node) { - // Only check variables in variable declaration lists - // and not variables in catch clauses and for loops. - var list = node.parent; - if (!tsutils_1.isVariableDeclarationList(list)) { - return; - } - var statement = list.parent; - if (!tsutils_1.isVariableStatement(statement)) { - return; - } - // Only check variables at the namespace/module-level or file-level - // and not variables declared inside functions and other things. - switch (statement.parent.kind) { - case ts.SyntaxKind.SourceFile: - case ts.SyntaxKind.ModuleBlock: - this.checkNode(node, exports.ARGUMENT_VARIABLES, statement); - } - }; - CompletedDocsWalker.prototype.checkComments = function (node, nodeDescriptor, comments, requirementNode) { + var comments = symbol.getDocumentationComment(typeChecker); + checkComments(node, describeNode(nodeType), comments, requirementNode); + } + function checkComments(node, nodeDescriptor, comments, requirementNode) { if (comments.map(function (comment) { return comment.text; }).join("").trim() === "") { - this.addDocumentationFailure(node, nodeDescriptor, requirementNode); + addDocumentationFailure(node, nodeDescriptor, requirementNode); } - }; - CompletedDocsWalker.prototype.addDocumentationFailure = function (node, nodeType, requirementNode) { + } + function addDocumentationFailure(node, nodeType, requirementNode) { var start = node.getStart(); var width = node.getText().split(/\r|\n/g)[0].length; - var description = this.describeDocumentationFailure(requirementNode, nodeType); - this.addFailureAt(start, width, description); - }; - CompletedDocsWalker.prototype.describeDocumentationFailure = function (node, nodeType) { - var _this = this; - var description = Rule.FAILURE_STRING_EXIST; - if (node.modifiers !== undefined) { - description += node.modifiers.map(function (modifier) { return _this.describeModifier(modifier.kind); }).join(",") + " "; - } - return "" + description + nodeType + "."; - }; - CompletedDocsWalker.prototype.describeModifier = function (kind) { - var description = ts.SyntaxKind[kind].toLowerCase().split("keyword")[0]; - var alias = CompletedDocsWalker.modifierAliases[description]; - return alias !== undefined ? alias : description; - }; - CompletedDocsWalker.prototype.describeNode = function (nodeType) { - return nodeType.replace("-", " "); - }; - CompletedDocsWalker.modifierAliases = { - export: "exported", - }; - return CompletedDocsWalker; -}(Lint.ProgramAwareRuleWalker)); -var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q; + var description = describeDocumentationFailure(requirementNode, nodeType); + context.addFailureAt(start, width, description); + } +} +function describeDocumentationFailure(node, nodeType) { + var description = Rule.FAILURE_STRING_EXIST; + if (node.modifiers !== undefined) { + description += node.modifiers.map(function (modifier) { return describeModifier(modifier.kind); }).join(" ") + " "; + } + return "" + description + nodeType + "."; +} +function describeModifier(kind) { + var description = ts.SyntaxKind[kind].toLowerCase().split("keyword")[0]; + var alias = modifierAliases[description]; + return alias !== undefined ? alias : description; +} +function describeNode(nodeType) { + return nodeType.replace("-", " "); +} +var templateObject_1, templateObject_2; |