1 | "use strict";
|
2 | var __extends = (this && this.__extends) || (function () {
|
3 | var extendStatics = function (d, b) {
|
4 | extendStatics = Object.setPrototypeOf ||
|
5 | ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
|
6 | function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
|
7 | return extendStatics(d, b);
|
8 | }
|
9 | return function (d, b) {
|
10 | extendStatics(d, b);
|
11 | function __() { this.constructor = d; }
|
12 | d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
|
13 | };
|
14 | })();
|
15 | var __makeTemplateObject = (this && this.__makeTemplateObject) || function (cooked, raw) {
|
16 | if (Object.defineProperty) { Object.defineProperty(cooked, "raw", { value: raw }); } else { cooked.raw = raw; }
|
17 | return cooked;
|
18 | };
|
19 | Object.defineProperty(exports, "__esModule", { value: true });
|
20 | var Lint = require("tslint");
|
21 | var ts = require("typescript");
|
22 | var NodeDocs_1 = require("./utils/NodeDocs");
|
23 | var defaultUselessWords = ['a', 'an', 'of', 'our', 'the'];
|
24 | var defaultAliases = {
|
25 | a: ['an', 'our']
|
26 | };
|
27 | var failureString = "This comment is roughly the same as the object's name. Either be more informative or don't include a comment.";
|
28 | var Rule = (function (_super) {
|
29 | __extends(Rule, _super);
|
30 | function Rule() {
|
31 | return _super !== null && _super.apply(this, arguments) || this;
|
32 | }
|
33 | Rule.prototype.apply = function (sourceFile) {
|
34 | return this.applyWithFunction(sourceFile, walk, parseOptions(this.getOptions().ruleArguments));
|
35 | };
|
36 | Rule.metadata = {
|
37 | description: 'Enforces that comments do more than just reiterate names of objects.',
|
38 | options: undefined,
|
39 | optionsDescription: 'Not configurable.',
|
40 | optionExamples: [
|
41 | true,
|
42 | [
|
43 | true,
|
44 | {
|
45 | aliases: {
|
46 | a: ['an', 'our'],
|
47 | emoji: ['smiley']
|
48 | },
|
49 | uselessWords: defaultUselessWords.concat(['also'])
|
50 | }
|
51 | ]
|
52 | ],
|
53 | rationale: Lint.Utils.dedent(templateObject_1 || (templateObject_1 = __makeTemplateObject(["\n The documentation for an object should not be equivalent to just the object's name.\n If we strip out non-alphabet characters, common words such as \"the\" or \"a\",\n and lowercase everything, they shouldn't be the same.\n\n Using informative documentation can be helpful for variables to help explain their usage.\n Alternately, if something's name is so descriptive that it doesn't need to be fully documented,\n just leave out documentation altogether.\n "], ["\n The documentation for an object should not be equivalent to just the object's name.\n If we strip out non-alphabet characters, common words such as \"the\" or \"a\",\n and lowercase everything, they shouldn't be the same.\n\n Using informative documentation can be helpful for variables to help explain their usage.\n Alternately, if something's name is so descriptive that it doesn't need to be fully documented,\n just leave out documentation altogether.\n "]))),
|
54 | issueClass: 'Non-SDL',
|
55 | issueType: 'Warning',
|
56 | severity: 'Moderate',
|
57 | level: 'Opportunity for Excellence',
|
58 | group: 'Clarity',
|
59 | recommendation: 'true',
|
60 | ruleName: 'informative-docs',
|
61 | type: 'maintainability',
|
62 | typescriptOnly: false
|
63 | };
|
64 | return Rule;
|
65 | }(Lint.Rules.AbstractRule));
|
66 | exports.Rule = Rule;
|
67 | function parseOptions(ruleArguments) {
|
68 | var rawOptions = ruleArguments.length === 0 ? {} : ruleArguments[0];
|
69 | return {
|
70 | aliases: parseAliasesOption(rawOptions.aliases === undefined ? defaultAliases : rawOptions.aliases),
|
71 | uselessWords: new Set(rawOptions.uselessWords === undefined ? defaultUselessWords : rawOptions.uselessWords)
|
72 | };
|
73 | }
|
74 | function parseAliasesOption(rawAliases) {
|
75 | var aliases = new Map();
|
76 | for (var _i = 0, _a = Object.keys(rawAliases); _i < _a.length; _i++) {
|
77 | var alias = _a[_i];
|
78 | for (var _b = 0, _c = rawAliases[alias]; _b < _c.length; _b++) {
|
79 | var aliasedName = _c[_b];
|
80 | aliases.set(aliasedName.toLowerCase(), alias.toLowerCase());
|
81 | }
|
82 | }
|
83 | return aliases;
|
84 | }
|
85 | function walk(context) {
|
86 | var _a = context.options, aliases = _a.aliases, uselessWords = _a.uselessWords;
|
87 | function nodeNameContainsUsefulWords(nameWords, docWords) {
|
88 | var realDocWords = new Set(docWords);
|
89 | for (var _i = 0, nameWords_1 = nameWords; _i < nameWords_1.length; _i++) {
|
90 | var nameWord = nameWords_1[_i];
|
91 | realDocWords.delete(nameWord);
|
92 | }
|
93 | uselessWords.forEach(function (uselessWord) {
|
94 | realDocWords.delete(uselessWord);
|
95 | });
|
96 | return realDocWords.size !== 0;
|
97 | }
|
98 | function normalizeWord(word) {
|
99 | word = word.toLowerCase();
|
100 | var aliasedWord = aliases.get(word);
|
101 | if (aliasedWord !== undefined) {
|
102 | word = aliasedWord;
|
103 | }
|
104 | return word;
|
105 | }
|
106 | function splitNameIntoWords(name) {
|
107 | if (name.length > 2 && name[0] === 'I' && Lint.Utils.isUpperCase(name[1])) {
|
108 | name = name.substring(1);
|
109 | }
|
110 | var nameSpaced = name
|
111 | .replace(/\W/g, '')
|
112 | .replace(/([a-z])([A-Z])/g, '$1 $2')
|
113 | .trim();
|
114 | if (nameSpaced.length === 0) {
|
115 | return undefined;
|
116 | }
|
117 | return nameSpaced.split(' ').map(normalizeWord);
|
118 | }
|
119 | function getNodeDocComments(node) {
|
120 | var docsRaw = NodeDocs_1.getApparentJsDoc(node);
|
121 | if (docsRaw === undefined) {
|
122 | return undefined;
|
123 | }
|
124 | var docs = docsRaw.map(function (doc) { return doc.comment; }).filter(function (comment) { return comment !== undefined; });
|
125 | if (docs.length === 0) {
|
126 | return undefined;
|
127 | }
|
128 | return docs
|
129 | .join(' ')
|
130 | .replace(/[^A-Za-z0-9 ]/g, '')
|
131 | .split(' ')
|
132 | .map(normalizeWord);
|
133 | }
|
134 | function verifyNodeWithName(node, name) {
|
135 | var docs = getNodeDocComments(node);
|
136 | if (docs === undefined) {
|
137 | return;
|
138 | }
|
139 | var nameSplit = splitNameIntoWords(name);
|
140 | if (nameSplit === undefined) {
|
141 | return;
|
142 | }
|
143 | if (!nodeNameContainsUsefulWords(nameSplit, docs)) {
|
144 | context.addFailureAtNode(node, failureString);
|
145 | }
|
146 | }
|
147 | function visitNode(node) {
|
148 | var name = NodeDocs_1.getNodeName(node);
|
149 | if (name !== undefined) {
|
150 | verifyNodeWithName(node, name);
|
151 | }
|
152 | return ts.forEachChild(node, visitNode);
|
153 | }
|
154 | return ts.forEachChild(context.sourceFile, visitNode);
|
155 | }
|
156 | var templateObject_1;
|
157 |
|
\ | No newline at end of file |