123 lines
6.6 KiB
JavaScript
123 lines
6.6 KiB
JavaScript
/**
|
|
* @license
|
|
* Copyright 2013 Palantir Technologies, Inc.
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
"use strict";
|
|
var __extends = (this && this.__extends) || (function () {
|
|
var extendStatics = Object.setPrototypeOf ||
|
|
({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
|
|
function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
|
|
return function (d, b) {
|
|
extendStatics(d, b);
|
|
function __() { this.constructor = d; }
|
|
d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
|
|
};
|
|
})();
|
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
var utils = require("tsutils");
|
|
var ts = require("typescript");
|
|
var Lint = require("../index");
|
|
var Rule = (function (_super) {
|
|
__extends(Rule, _super);
|
|
function Rule() {
|
|
return _super !== null && _super.apply(this, arguments) || this;
|
|
}
|
|
Rule.prototype.apply = function (sourceFile) {
|
|
return this.applyWithWalker(new JsdocWalker(sourceFile, this.getOptions()));
|
|
};
|
|
return Rule;
|
|
}(Lint.Rules.AbstractRule));
|
|
/* tslint:disable:object-literal-sort-keys */
|
|
Rule.metadata = {
|
|
ruleName: "jsdoc-format",
|
|
description: "Enforces basic format rules for JSDoc comments.",
|
|
descriptionDetails: (_a = ["\n The following rules are enforced for JSDoc comments (comments starting with `/**`):\n\n * each line contains an asterisk and asterisks must be aligned\n * each asterisk must be followed by either a space or a newline (except for the first and the last)\n * the only characters before the asterisk on each line must be whitespace characters\n * one line comments must start with `/** ` and end with `*/`"], _a.raw = ["\n The following rules are enforced for JSDoc comments (comments starting with \\`/**\\`):\n\n * each line contains an asterisk and asterisks must be aligned\n * each asterisk must be followed by either a space or a newline (except for the first and the last)\n * the only characters before the asterisk on each line must be whitespace characters\n * one line comments must start with \\`/** \\` and end with \\`*/\\`"], Lint.Utils.dedent(_a)),
|
|
rationale: "Helps maintain a consistent, readable style for JSDoc comments.",
|
|
optionsDescription: "Not configurable.",
|
|
options: null,
|
|
optionExamples: ["true"],
|
|
type: "style",
|
|
typescriptOnly: false,
|
|
};
|
|
/* tslint:enable:object-literal-sort-keys */
|
|
Rule.ALIGNMENT_FAILURE_STRING = "asterisks in jsdoc must be aligned";
|
|
Rule.FORMAT_FAILURE_STRING = "jsdoc is not formatted correctly on this line";
|
|
exports.Rule = Rule;
|
|
var JsdocWalker = (function (_super) {
|
|
__extends(JsdocWalker, _super);
|
|
function JsdocWalker() {
|
|
return _super !== null && _super.apply(this, arguments) || this;
|
|
}
|
|
JsdocWalker.prototype.visitSourceFile = function (node) {
|
|
var _this = this;
|
|
utils.forEachComment(node, function (fullText, comment) {
|
|
if (comment.kind === ts.SyntaxKind.MultiLineCommentTrivia) {
|
|
_this.findFailuresForJsdocComment(fullText.substring(comment.pos, comment.end), comment.pos);
|
|
}
|
|
});
|
|
};
|
|
JsdocWalker.prototype.findFailuresForJsdocComment = function (commentText, startingPosition) {
|
|
var currentPosition = startingPosition;
|
|
// the file may be different depending on the OS it was originally authored on
|
|
// can't rely on require('os').EOL or process.platform as that is the execution env
|
|
// regex is: split optionally on \r\n, but alwasy split on \n if no \r exists
|
|
var lines = commentText.split(/\r?\n/);
|
|
var firstLine = lines[0];
|
|
var jsdocPosition = currentPosition;
|
|
// regex is: start of string, followed by any amount of whitespace, followed by /** but not more than 2 **
|
|
var isJsdocMatch = firstLine.match(/^\s*\/\*\*([^*]|$)/);
|
|
if (isJsdocMatch != null) {
|
|
if (lines.length === 1) {
|
|
var firstLineMatch = firstLine.match(/^\s*\/\*\* (.* )?\*\/$/);
|
|
if (firstLineMatch == null) {
|
|
this.addFailureAt(jsdocPosition, firstLine.length, Rule.FORMAT_FAILURE_STRING);
|
|
}
|
|
return;
|
|
}
|
|
var indexToMatch = firstLine.indexOf("**") + this.getLineAndCharacterOfPosition(currentPosition).character;
|
|
// all lines but the first and last
|
|
var otherLines = lines.splice(1, lines.length - 2);
|
|
jsdocPosition += firstLine.length + 1; // + 1 for the splitted-out newline
|
|
for (var _i = 0, otherLines_1 = otherLines; _i < otherLines_1.length; _i++) {
|
|
var line = otherLines_1[_i];
|
|
// regex is: start of string, followed by any amount of whitespace, followed by *,
|
|
// followed by either a space or the end of the string
|
|
var asteriskMatch = line.match(/^\s*\*( |$)/);
|
|
if (asteriskMatch == null) {
|
|
this.addFailureAt(jsdocPosition, line.length, Rule.FORMAT_FAILURE_STRING);
|
|
}
|
|
var asteriskIndex = line.indexOf("*");
|
|
if (asteriskIndex !== indexToMatch) {
|
|
this.addFailureAt(jsdocPosition, line.length, Rule.ALIGNMENT_FAILURE_STRING);
|
|
}
|
|
jsdocPosition += line.length + 1; // + 1 for the splitted-out newline
|
|
}
|
|
var lastLine = lines[lines.length - 1];
|
|
// regex is: start of string, followed by any amount of whitespace, followed by */,
|
|
// followed by the end of the string
|
|
var endBlockCommentMatch = lastLine.match(/^\s*\*\/$/);
|
|
if (endBlockCommentMatch == null) {
|
|
this.addFailureAt(jsdocPosition, lastLine.length, Rule.FORMAT_FAILURE_STRING);
|
|
}
|
|
var lastAsteriskIndex = lastLine.indexOf("*");
|
|
if (lastAsteriskIndex !== indexToMatch) {
|
|
this.addFailureAt(jsdocPosition, lastLine.length, Rule.ALIGNMENT_FAILURE_STRING);
|
|
}
|
|
}
|
|
};
|
|
return JsdocWalker;
|
|
}(Lint.RuleWalker));
|
|
var _a;
|