2017-03-01 18:28:51 +01:00
|
|
|
/* @internal */
|
2016-09-07 16:04:46 +02:00
|
|
|
namespace ts.JsDoc {
|
|
|
|
const jsDocTagNames = [
|
|
|
|
"augments",
|
|
|
|
"author",
|
|
|
|
"argument",
|
|
|
|
"borrows",
|
|
|
|
"class",
|
|
|
|
"constant",
|
|
|
|
"constructor",
|
|
|
|
"constructs",
|
|
|
|
"default",
|
|
|
|
"deprecated",
|
|
|
|
"description",
|
|
|
|
"event",
|
|
|
|
"example",
|
|
|
|
"extends",
|
|
|
|
"field",
|
|
|
|
"fileOverview",
|
|
|
|
"function",
|
|
|
|
"ignore",
|
2017-11-06 22:18:21 +01:00
|
|
|
"inheritDoc",
|
2016-09-07 16:04:46 +02:00
|
|
|
"inner",
|
|
|
|
"lends",
|
|
|
|
"link",
|
|
|
|
"memberOf",
|
2016-12-14 01:36:54 +01:00
|
|
|
"method",
|
2016-09-07 16:04:46 +02:00
|
|
|
"name",
|
|
|
|
"namespace",
|
|
|
|
"param",
|
|
|
|
"private",
|
2017-05-04 23:16:09 +02:00
|
|
|
"prop",
|
2016-09-07 16:04:46 +02:00
|
|
|
"property",
|
|
|
|
"public",
|
|
|
|
"requires",
|
|
|
|
"returns",
|
|
|
|
"see",
|
|
|
|
"since",
|
|
|
|
"static",
|
2018-02-17 01:27:57 +01:00
|
|
|
"template",
|
2016-09-07 16:04:46 +02:00
|
|
|
"throws",
|
|
|
|
"type",
|
|
|
|
"typedef",
|
|
|
|
"version"
|
|
|
|
];
|
2017-03-01 00:41:35 +01:00
|
|
|
let jsDocTagNameCompletionEntries: CompletionEntry[];
|
2017-03-02 02:46:35 +01:00
|
|
|
let jsDocTagCompletionEntries: CompletionEntry[];
|
2016-09-07 16:04:46 +02:00
|
|
|
|
2018-03-30 18:43:12 +02:00
|
|
|
export function getJsDocCommentsFromDeclarations(declarations: ReadonlyArray<Declaration>): SymbolDisplayPart[] {
|
2016-09-15 20:53:04 +02:00
|
|
|
// Only collect doc comments from duplicate declarations once:
|
|
|
|
// In case of a union property there might be same declaration multiple times
|
|
|
|
// which only varies in type parameter
|
|
|
|
// Eg. const a: Array<string> | Array<number>; a.length
|
|
|
|
// The property length will have two declarations of property length coming
|
|
|
|
// from Array<T> - Array<string> and Array<number>
|
2018-01-11 19:49:39 +01:00
|
|
|
const documentationComment: SymbolDisplayPart[] = [];
|
2016-09-15 20:53:04 +02:00
|
|
|
forEachUnique(declarations, declaration => {
|
2018-01-11 19:49:39 +01:00
|
|
|
for (const { comment } of getCommentHavingNodes(declaration)) {
|
|
|
|
if (comment === undefined) continue;
|
|
|
|
if (documentationComment.length) {
|
|
|
|
documentationComment.push(lineBreakPart());
|
2016-09-07 16:04:46 +02:00
|
|
|
}
|
2018-01-11 19:49:39 +01:00
|
|
|
documentationComment.push(textPart(comment));
|
|
|
|
}
|
2016-09-15 20:53:04 +02:00
|
|
|
});
|
|
|
|
return documentationComment;
|
|
|
|
}
|
2016-09-07 16:04:46 +02:00
|
|
|
|
2018-01-11 19:49:39 +01:00
|
|
|
function getCommentHavingNodes(declaration: Declaration): ReadonlyArray<JSDoc | JSDocTag> {
|
|
|
|
switch (declaration.kind) {
|
|
|
|
case SyntaxKind.JSDocPropertyTag:
|
|
|
|
return [declaration as JSDocPropertyTag];
|
|
|
|
case SyntaxKind.JSDocTypedefTag:
|
|
|
|
return [(declaration as JSDocTypedefTag).parent];
|
|
|
|
default:
|
|
|
|
return getJSDocCommentsAndTags(declaration);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2017-10-30 18:27:19 +01:00
|
|
|
export function getJsDocTagsFromDeclarations(declarations?: Declaration[]): JSDocTagInfo[] {
|
2016-12-13 00:29:29 +01:00
|
|
|
// Only collect doc comments from duplicate declarations once.
|
|
|
|
const tags: JSDocTagInfo[] = [];
|
|
|
|
forEachUnique(declarations, declaration => {
|
2017-07-10 20:26:59 +02:00
|
|
|
for (const tag of getJSDocTags(declaration)) {
|
2017-10-30 18:27:19 +01:00
|
|
|
tags.push({ name: tag.tagName.text, text: getCommentText(tag) });
|
2016-12-13 00:29:29 +01:00
|
|
|
}
|
|
|
|
});
|
|
|
|
return tags;
|
|
|
|
}
|
|
|
|
|
2018-01-11 19:49:39 +01:00
|
|
|
function getCommentText(tag: JSDocTag): string | undefined {
|
2017-10-30 18:27:19 +01:00
|
|
|
const { comment } = tag;
|
|
|
|
switch (tag.kind) {
|
|
|
|
case SyntaxKind.JSDocAugmentsTag:
|
|
|
|
return withNode((tag as JSDocAugmentsTag).class);
|
|
|
|
case SyntaxKind.JSDocTemplateTag:
|
|
|
|
return withList((tag as JSDocTemplateTag).typeParameters);
|
|
|
|
case SyntaxKind.JSDocTypeTag:
|
|
|
|
return withNode((tag as JSDocTypeTag).typeExpression);
|
|
|
|
case SyntaxKind.JSDocTypedefTag:
|
|
|
|
case SyntaxKind.JSDocPropertyTag:
|
|
|
|
case SyntaxKind.JSDocParameterTag:
|
|
|
|
const { name } = tag as JSDocTypedefTag | JSDocPropertyTag | JSDocParameterTag;
|
|
|
|
return name ? withNode(name) : comment;
|
|
|
|
default:
|
|
|
|
return comment;
|
|
|
|
}
|
|
|
|
|
|
|
|
function withNode(node: Node) {
|
2018-01-11 19:49:39 +01:00
|
|
|
return addComment(node.getText());
|
2017-10-30 18:27:19 +01:00
|
|
|
}
|
|
|
|
|
|
|
|
function withList(list: NodeArray<Node>): string {
|
2018-01-11 19:49:39 +01:00
|
|
|
return addComment(list.map(x => x.getText()).join(", "));
|
|
|
|
}
|
|
|
|
|
|
|
|
function addComment(s: string) {
|
|
|
|
return comment === undefined ? s : `${s} ${comment}`;
|
2017-10-30 18:27:19 +01:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2016-09-15 20:53:04 +02:00
|
|
|
/**
|
|
|
|
* Iterates through 'array' by index and performs the callback on each element of array until the callback
|
|
|
|
* returns a truthy value, then returns that value.
|
|
|
|
* If no such value is found, the callback is applied to each element of array and undefined is returned.
|
|
|
|
*/
|
2018-03-30 18:43:12 +02:00
|
|
|
function forEachUnique<T, U>(array: ReadonlyArray<T>, callback: (element: T, index: number) => U): U {
|
2016-09-15 20:53:04 +02:00
|
|
|
if (array) {
|
2016-12-19 19:12:35 +01:00
|
|
|
for (let i = 0; i < array.length; i++) {
|
2018-01-08 19:39:52 +01:00
|
|
|
if (array.indexOf(array[i]) === i) {
|
2016-09-15 20:53:04 +02:00
|
|
|
const result = callback(array[i], i);
|
|
|
|
if (result) {
|
|
|
|
return result;
|
2016-09-07 16:04:46 +02:00
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
2016-09-15 20:53:04 +02:00
|
|
|
return undefined;
|
2016-09-07 16:04:46 +02:00
|
|
|
}
|
|
|
|
|
2017-03-02 02:46:35 +01:00
|
|
|
export function getJSDocTagNameCompletions(): CompletionEntry[] {
|
2018-03-01 23:20:18 +01:00
|
|
|
return jsDocTagNameCompletionEntries || (jsDocTagNameCompletionEntries = map(jsDocTagNames, tagName => {
|
2016-09-07 16:04:46 +02:00
|
|
|
return {
|
|
|
|
name: tagName,
|
|
|
|
kind: ScriptElementKind.keyword,
|
|
|
|
kindModifiers: "",
|
|
|
|
sortText: "0",
|
|
|
|
};
|
|
|
|
}));
|
|
|
|
}
|
|
|
|
|
2017-10-26 19:58:33 +02:00
|
|
|
export const getJSDocTagNameCompletionDetails = getJSDocTagCompletionDetails;
|
|
|
|
|
2017-03-02 02:46:35 +01:00
|
|
|
export function getJSDocTagCompletions(): CompletionEntry[] {
|
2018-03-01 23:20:18 +01:00
|
|
|
return jsDocTagCompletionEntries || (jsDocTagCompletionEntries = map(jsDocTagNames, tagName => {
|
2017-03-02 02:46:35 +01:00
|
|
|
return {
|
|
|
|
name: `@${tagName}`,
|
|
|
|
kind: ScriptElementKind.keyword,
|
|
|
|
kindModifiers: "",
|
|
|
|
sortText: "0"
|
2017-03-03 16:00:52 +01:00
|
|
|
};
|
2017-03-02 02:46:35 +01:00
|
|
|
}));
|
2016-09-07 16:04:46 +02:00
|
|
|
}
|
|
|
|
|
2017-10-26 19:58:33 +02:00
|
|
|
export function getJSDocTagCompletionDetails(name: string): CompletionEntryDetails {
|
|
|
|
return {
|
|
|
|
name,
|
|
|
|
kind: ScriptElementKind.unknown, // TODO: should have its own kind?
|
|
|
|
kindModifiers: "",
|
|
|
|
displayParts: [textPart(name)],
|
|
|
|
documentation: emptyArray,
|
|
|
|
tags: emptyArray,
|
|
|
|
codeActions: undefined,
|
|
|
|
};
|
|
|
|
}
|
|
|
|
|
2017-06-07 21:28:52 +02:00
|
|
|
export function getJSDocParameterNameCompletions(tag: JSDocParameterTag): CompletionEntry[] {
|
2017-07-26 19:57:29 +02:00
|
|
|
if (!isIdentifier(tag.name)) {
|
|
|
|
return emptyArray;
|
|
|
|
}
|
2017-07-25 22:16:34 +02:00
|
|
|
const nameThusFar = tag.name.text;
|
2017-06-07 21:28:52 +02:00
|
|
|
const jsdoc = tag.parent;
|
|
|
|
const fn = jsdoc.parent;
|
2018-03-01 23:20:18 +01:00
|
|
|
if (!isFunctionLike(fn)) return [];
|
2017-06-07 21:28:52 +02:00
|
|
|
|
|
|
|
return mapDefined(fn.parameters, param => {
|
|
|
|
if (!isIdentifier(param.name)) return undefined;
|
|
|
|
|
2017-07-25 22:16:34 +02:00
|
|
|
const name = param.name.text;
|
2017-07-26 20:09:24 +02:00
|
|
|
if (jsdoc.tags.some(t => t !== tag && isJSDocParameterTag(t) && isIdentifier(t.name) && t.name.escapedText === name)
|
2017-06-08 00:50:26 +02:00
|
|
|
|| nameThusFar !== undefined && !startsWith(name, nameThusFar)) {
|
2017-06-07 21:28:52 +02:00
|
|
|
return undefined;
|
2017-06-08 00:50:26 +02:00
|
|
|
}
|
2017-06-07 21:28:52 +02:00
|
|
|
|
|
|
|
return { name, kind: ScriptElementKind.parameterElement, kindModifiers: "", sortText: "0" };
|
|
|
|
});
|
|
|
|
}
|
|
|
|
|
2017-10-26 19:58:33 +02:00
|
|
|
export function getJSDocParameterNameCompletionDetails(name: string): CompletionEntryDetails {
|
|
|
|
return {
|
|
|
|
name,
|
|
|
|
kind: ScriptElementKind.parameterElement,
|
|
|
|
kindModifiers: "",
|
|
|
|
displayParts: [textPart(name)],
|
|
|
|
documentation: emptyArray,
|
|
|
|
tags: emptyArray,
|
|
|
|
codeActions: undefined,
|
|
|
|
};
|
|
|
|
}
|
|
|
|
|
2016-09-07 16:04:46 +02:00
|
|
|
/**
|
|
|
|
* Checks if position points to a valid position to add JSDoc comments, and if so,
|
|
|
|
* returns the appropriate template. Otherwise returns an empty string.
|
2017-12-12 00:56:31 +01:00
|
|
|
* Valid positions are
|
|
|
|
* - outside of comments, statements, and expressions, and
|
|
|
|
* - preceding a:
|
|
|
|
* - function/constructor/method declaration
|
|
|
|
* - class declarations
|
|
|
|
* - variable statements
|
|
|
|
* - namespace declarations
|
|
|
|
* - interface declarations
|
|
|
|
* - method signatures
|
2017-12-12 01:15:32 +01:00
|
|
|
* - type alias declarations
|
2016-09-07 16:04:46 +02:00
|
|
|
*
|
|
|
|
* Hosts should ideally check that:
|
|
|
|
* - The line is all whitespace up to 'position' before performing the insertion.
|
|
|
|
* - If the keystroke sequence "/\*\*" induced the call, we also check that the next
|
|
|
|
* non-whitespace character is '*', which (approximately) indicates whether we added
|
|
|
|
* the second '*' to complete an existing (JSDoc) comment.
|
|
|
|
* @param fileName The file in which to perform the check.
|
|
|
|
* @param position The (character-indexed) position in the file where the check should
|
|
|
|
* be performed.
|
|
|
|
*/
|
2017-11-02 19:08:26 +01:00
|
|
|
|
|
|
|
export function getDocCommentTemplateAtPosition(newLine: string, sourceFile: SourceFile, position: number): TextInsertion | undefined {
|
2016-09-07 16:04:46 +02:00
|
|
|
// Check if in a context where we don't want to perform any insertion
|
|
|
|
if (isInString(sourceFile, position) || isInComment(sourceFile, position) || hasDocComment(sourceFile, position)) {
|
|
|
|
return undefined;
|
|
|
|
}
|
|
|
|
|
2017-05-12 17:33:31 +02:00
|
|
|
const tokenAtPos = getTokenAtPosition(sourceFile, position, /*includeJsDocComment*/ false);
|
2016-09-07 16:04:46 +02:00
|
|
|
const tokenStart = tokenAtPos.getStart();
|
|
|
|
if (!tokenAtPos || tokenStart < position) {
|
|
|
|
return undefined;
|
|
|
|
}
|
|
|
|
|
2017-09-07 16:21:47 +02:00
|
|
|
const commentOwnerInfo = getCommentOwnerInfo(tokenAtPos);
|
|
|
|
if (!commentOwnerInfo) {
|
2017-12-12 00:56:31 +01:00
|
|
|
return undefined;
|
2016-09-07 16:04:46 +02:00
|
|
|
}
|
2017-09-07 16:21:47 +02:00
|
|
|
const { commentOwner, parameters } = commentOwnerInfo;
|
2017-12-12 00:56:31 +01:00
|
|
|
if (commentOwner.getStart() < position) {
|
2016-09-07 16:04:46 +02:00
|
|
|
return undefined;
|
|
|
|
}
|
|
|
|
|
2017-12-12 00:56:31 +01:00
|
|
|
if (!parameters || parameters.length === 0) {
|
|
|
|
// if there are no parameters, just complete to a single line JSDoc comment
|
|
|
|
const singleLineResult = "/** */";
|
|
|
|
return { newText: singleLineResult, caretOffset: 3 };
|
2017-11-02 17:55:56 +01:00
|
|
|
}
|
|
|
|
|
2016-09-07 16:04:46 +02:00
|
|
|
const posLineAndChar = sourceFile.getLineAndCharacterOfPosition(position);
|
|
|
|
const lineStart = sourceFile.getLineStarts()[posLineAndChar.line];
|
|
|
|
|
2017-03-08 21:41:20 +01:00
|
|
|
// replace non-whitespace characters in prefix with spaces.
|
|
|
|
const indentationStr = sourceFile.text.substr(lineStart, posLineAndChar.character).replace(/\S/i, () => " ");
|
2016-12-08 19:07:11 +01:00
|
|
|
const isJavaScriptFile = hasJavaScriptFileExtension(sourceFile.fileName);
|
2016-09-07 16:04:46 +02:00
|
|
|
|
2017-12-12 00:56:31 +01:00
|
|
|
let docParams = "";
|
|
|
|
for (let i = 0; i < parameters.length; i++) {
|
|
|
|
const currentName = parameters[i].name;
|
2018-02-17 03:38:00 +01:00
|
|
|
const paramName = currentName.kind === SyntaxKind.Identifier ? currentName.escapedText : "param" + i;
|
2017-12-12 00:56:31 +01:00
|
|
|
if (isJavaScriptFile) {
|
|
|
|
docParams += `${indentationStr} * @param {any} ${paramName}${newLine}`;
|
|
|
|
}
|
|
|
|
else {
|
|
|
|
docParams += `${indentationStr} * @param ${paramName}${newLine}`;
|
|
|
|
}
|
|
|
|
}
|
2016-09-07 16:04:46 +02:00
|
|
|
|
|
|
|
// A doc comment consists of the following
|
|
|
|
// * The opening comment line
|
|
|
|
// * the first line (without a param) for the object's untagged info (this is also where the caret ends up)
|
|
|
|
// * the '@param'-tagged lines
|
|
|
|
// * TODO: other tags.
|
|
|
|
// * the closing comment line
|
|
|
|
// * if the caret was directly in front of the object, then we add an extra line and indentation.
|
|
|
|
const preamble = "/**" + newLine +
|
|
|
|
indentationStr + " * ";
|
|
|
|
const result =
|
|
|
|
preamble + newLine +
|
|
|
|
docParams +
|
|
|
|
indentationStr + " */" +
|
|
|
|
(tokenStart === position ? newLine + indentationStr : "");
|
|
|
|
|
|
|
|
return { newText: result, caretOffset: preamble.length };
|
|
|
|
}
|
|
|
|
|
2017-09-07 16:21:47 +02:00
|
|
|
interface CommentOwnerInfo {
|
|
|
|
readonly commentOwner: Node;
|
2017-12-12 00:56:31 +01:00
|
|
|
readonly parameters?: ReadonlyArray<ParameterDeclaration>;
|
2017-09-07 16:21:47 +02:00
|
|
|
}
|
|
|
|
function getCommentOwnerInfo(tokenAtPos: Node): CommentOwnerInfo | undefined {
|
|
|
|
for (let commentOwner = tokenAtPos; commentOwner; commentOwner = commentOwner.parent) {
|
|
|
|
switch (commentOwner.kind) {
|
|
|
|
case SyntaxKind.FunctionDeclaration:
|
|
|
|
case SyntaxKind.MethodDeclaration:
|
|
|
|
case SyntaxKind.Constructor:
|
2017-10-28 01:46:39 +02:00
|
|
|
case SyntaxKind.MethodSignature:
|
|
|
|
const { parameters } = commentOwner as FunctionDeclaration | MethodDeclaration | ConstructorDeclaration | MethodSignature;
|
2017-09-07 16:21:47 +02:00
|
|
|
return { commentOwner, parameters };
|
2016-09-07 16:04:46 +02:00
|
|
|
|
2017-12-12 00:56:31 +01:00
|
|
|
case SyntaxKind.ClassDeclaration:
|
|
|
|
case SyntaxKind.InterfaceDeclaration:
|
|
|
|
case SyntaxKind.PropertySignature:
|
|
|
|
case SyntaxKind.EnumDeclaration:
|
|
|
|
case SyntaxKind.EnumMember:
|
|
|
|
case SyntaxKind.TypeAliasDeclaration:
|
|
|
|
return { commentOwner };
|
|
|
|
|
2017-09-07 16:21:47 +02:00
|
|
|
case SyntaxKind.VariableStatement: {
|
|
|
|
const varStatement = <VariableStatement>commentOwner;
|
|
|
|
const varDeclarations = varStatement.declarationList.declarations;
|
|
|
|
const parameters = varDeclarations.length === 1 && varDeclarations[0].initializer
|
|
|
|
? getParametersFromRightHandSideOfAssignment(varDeclarations[0].initializer)
|
|
|
|
: undefined;
|
2017-12-12 00:56:31 +01:00
|
|
|
return { commentOwner, parameters };
|
2017-09-07 16:21:47 +02:00
|
|
|
}
|
2016-09-07 16:04:46 +02:00
|
|
|
|
2017-09-07 16:21:47 +02:00
|
|
|
case SyntaxKind.SourceFile:
|
|
|
|
return undefined;
|
|
|
|
|
2017-12-12 00:56:31 +01:00
|
|
|
case SyntaxKind.ModuleDeclaration:
|
|
|
|
// If in walking up the tree, we hit a a nested namespace declaration,
|
|
|
|
// then we must be somewhere within a dotted namespace name; however we don't
|
|
|
|
// want to give back a JSDoc template for the 'b' or 'c' in 'namespace a.b.c { }'.
|
|
|
|
return commentOwner.parent.kind === SyntaxKind.ModuleDeclaration ? undefined : { commentOwner };
|
|
|
|
|
2017-09-07 16:21:47 +02:00
|
|
|
case SyntaxKind.BinaryExpression: {
|
|
|
|
const be = commentOwner as BinaryExpression;
|
2018-03-01 23:20:18 +01:00
|
|
|
if (getSpecialPropertyAssignmentKind(be) === SpecialPropertyAssignmentKind.None) {
|
2017-09-07 16:21:47 +02:00
|
|
|
return undefined;
|
|
|
|
}
|
|
|
|
const parameters = isFunctionLike(be.right) ? be.right.parameters : emptyArray;
|
|
|
|
return { commentOwner, parameters };
|
|
|
|
}
|
2016-09-07 16:04:46 +02:00
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Digs into an an initializer or RHS operand of an assignment operation
|
|
|
|
* to get the parameters of an apt signature corresponding to a
|
|
|
|
* function expression or a class expression.
|
|
|
|
*
|
|
|
|
* @param rightHandSide the expression which may contain an appropriate set of parameters
|
|
|
|
* @returns the parameters of a signature found on the RHS if one exists; otherwise 'emptyArray'.
|
|
|
|
*/
|
2017-07-18 19:38:21 +02:00
|
|
|
function getParametersFromRightHandSideOfAssignment(rightHandSide: Expression): ReadonlyArray<ParameterDeclaration> {
|
2016-09-07 16:04:46 +02:00
|
|
|
while (rightHandSide.kind === SyntaxKind.ParenthesizedExpression) {
|
|
|
|
rightHandSide = (<ParenthesizedExpression>rightHandSide).expression;
|
|
|
|
}
|
|
|
|
|
|
|
|
switch (rightHandSide.kind) {
|
|
|
|
case SyntaxKind.FunctionExpression:
|
|
|
|
case SyntaxKind.ArrowFunction:
|
|
|
|
return (<FunctionExpression>rightHandSide).parameters;
|
2018-04-20 18:43:38 +02:00
|
|
|
case SyntaxKind.ClassExpression: {
|
|
|
|
const ctr = find((rightHandSide as ClassExpression).members, isConstructorDeclaration);
|
|
|
|
return ctr && ctr.parameters;
|
|
|
|
}
|
2016-09-07 16:04:46 +02:00
|
|
|
}
|
|
|
|
|
|
|
|
return emptyArray;
|
|
|
|
}
|
|
|
|
}
|