microsoft/TypeScript
1
0
Fork 0
mirror of https://github.com/microsoft/TypeScript.git synced 2026-02-05 16:38:05 -06:00
Code Issues Packages Projects Releases 212 Wiki Activity

Merge pull request #19544 from uniqueiniquity/interfaceJsDoc

Browse Source 
Insert JsDoc comment templates for additional nodes
This commit is contained in:
Benjamin Lichtman 2017-11-06 09:49:59 -08:00 committed by GitHub
commit 4977bf4328
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
18 changed files with 150 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/harness/harnessLanguageService.ts
View File

@ -495,7 +495,7 @@ namespace Harness.LanguageService {
getFormattingEditsAfterKeystroke(fileName: string, position: number, key: string, options: ts.FormatCodeOptions): ts.TextChange[] {
return unwrapJSONCallResult(this.shim.getFormattingEditsAfterKeystroke(fileName, position, key, JSON.stringify(options)));
}
getDocCommentTemplateAtPosition(fileName: string, position: number): ts.TextInsertion {
getDocCommentTemplateAtPosition(fileName: string, position: number): ts.TextInsertion | undefined {
return unwrapJSONCallResult(this.shim.getDocCommentTemplateAtPosition(fileName, position));
}
isValidBraceCompletionAtPosition(fileName: string, position: number, openingBrace: number): boolean {

72
src/services/jsDoc.ts
View File

@ -1,5 +1,6 @@
/* @internal */
namespace ts.JsDoc {
const singleLineTemplate = { newText: "/** */", caretOffset: 3 };
const jsDocTagNames = [
"augments",
"author",
@ -195,13 +196,9 @@ namespace ts.JsDoc {
/**
* Checks if position points to a valid position to add JSDoc comments, and if so,
* returns the appropriate template. Otherwise returns an empty string.
* Valid positions are
* - outside of comments, statements, and expressions, and
* - preceding a:
* - function/constructor/method declaration
* - class declarations
* - variable statements
* - namespace declarations
* Invalid positions are
* - within comments, strings (including template literals and regex), and JSXText
* - within a token
*
* Hosts should ideally check that:
* - The line is all whitespace up to 'position' before performing the insertion.
@ -212,7 +209,8 @@ namespace ts.JsDoc {
* @param position The (character-indexed) position in the file where the check should
* be performed.
*/
export function getDocCommentTemplateAtPosition(newLine: string, sourceFile: SourceFile, position: number): TextInsertion {
export function getDocCommentTemplateAtPosition(newLine: string, sourceFile: SourceFile, position: number): TextInsertion | undefined {
// 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;
@ -226,13 +224,21 @@ namespace ts.JsDoc {
const commentOwnerInfo = getCommentOwnerInfo(tokenAtPos);
if (!commentOwnerInfo) {
return undefined;
// if climbing the tree did not find a declaration with parameters, complete to a single line comment
return singleLineTemplate;
}
const { commentOwner, parameters } = commentOwnerInfo;
if (commentOwner.getStart() < position) {
if (commentOwner.kind === SyntaxKind.JsxText) {
return undefined;
}
if (commentOwner.getStart() < position || parameters.length === 0) {
// if climbing the tree found a declaration with parameters but the request was made inside it
// or if there are no parameters, complete to a single line comment
return singleLineTemplate;
}
const posLineAndChar = sourceFile.getLineAndCharacterOfPosition(position);
const lineStart = sourceFile.getLineStarts()[posLineAndChar.line];
@ -240,21 +246,11 @@ namespace ts.JsDoc {
const indentationStr = sourceFile.text.substr(lineStart, posLineAndChar.character).replace(/\S/i, () => " ");
const isJavaScriptFile = hasJavaScriptFileExtension(sourceFile.fileName);
let docParams = "";
if (parameters) {
for (let i = 0; i < parameters.length; i++) {
const currentName = parameters[i].name;
const paramName = currentName.kind === SyntaxKind.Identifier ?
(<Identifier>currentName).escapedText :
"param" + i;
if (isJavaScriptFile) {
docParams += `${indentationStr} * @param {any} ${paramName}${newLine}`;
}
else {
docParams += `${indentationStr} * @param ${paramName}${newLine}`;
}
}
}
const docParams = parameters.map(({name}, i) => {
const nameText = isIdentifier(name) ? name.text : `param${i}`;
const type = isJavaScriptFile ? "{any} " : "";
return `${indentationStr} * @param ${type}${nameText}${newLine}`;
}).join("");
// A doc comment consists of the following
// * The opening comment line
@ -276,43 +272,30 @@ namespace ts.JsDoc {
interface CommentOwnerInfo {
readonly commentOwner: Node;
readonly parameters?: ReadonlyArray<ParameterDeclaration>;
readonly parameters: ReadonlyArray<ParameterDeclaration>;
}
function getCommentOwnerInfo(tokenAtPos: Node): CommentOwnerInfo | undefined {
// TODO: add support for:
// - enums/enum members
// - interfaces
// - property declarations
// - potentially property assignments
for (let commentOwner = tokenAtPos; commentOwner; commentOwner = commentOwner.parent) {
switch (commentOwner.kind) {
case SyntaxKind.FunctionDeclaration:
case SyntaxKind.MethodDeclaration:
case SyntaxKind.Constructor:
const { parameters } = commentOwner as FunctionDeclaration | MethodDeclaration | ConstructorDeclaration;
case SyntaxKind.MethodSignature:
const { parameters } = commentOwner as FunctionDeclaration | MethodDeclaration | ConstructorDeclaration | MethodSignature;
return { commentOwner, parameters };
case SyntaxKind.ClassDeclaration:
return { commentOwner };
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;
return { commentOwner, parameters };
return parameters ? { commentOwner, parameters } : undefined;
}
case SyntaxKind.SourceFile:
return undefined;
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 };
case SyntaxKind.BinaryExpression: {
const be = commentOwner as BinaryExpression;
if (getSpecialPropertyAssignmentKind(be) === ts.SpecialPropertyAssignmentKind.None) {
@ -321,6 +304,11 @@ namespace ts.JsDoc {
const parameters = isFunctionLike(be.right) ? be.right.parameters : emptyArray;
return { commentOwner, parameters };
}
case SyntaxKind.JsxText: {
const parameters: ReadonlyArray<ParameterDeclaration> = emptyArray;
return { commentOwner, parameters };
}
}
}
}

2
src/services/services.ts
View File

@ -1808,7 +1808,7 @@ namespace ts {
}
}
function getDocCommentTemplateAtPosition(fileName: string, position: number): TextInsertion {
function getDocCommentTemplateAtPosition(fileName: string, position: number): TextInsertion | undefined {
return JsDoc.getDocCommentTemplateAtPosition(getNewLineOrDefaultFromHost(host), syntaxTreeCache.getCurrentSourceFile(fileName), position);
}

7
tests/cases/fourslash/docCommentTemplateClassDecl01.ts
View File

@ -11,8 +11,5 @@
//// }
////}
verify.docCommentTemplateAt("decl", /*newTextOffset*/ 8,
`/**
*
*/
`);
verify.docCommentTemplateAt("decl", /*newTextOffset*/ 3,
"/** */");

26
tests/cases/fourslash/docCommentTemplateClassDeclMethods01.ts
View File

@ -1,9 +1,7 @@
/// <reference path='fourslash.ts' />
const enum Indentation {
Standard = 8,
Indented = 12,
}
const singleLineOffset = 3;
const multiLineOffset = 12;
////class C {
@ -16,26 +14,22 @@ const enum Indentation {
//// }
////}
verify.docCommentTemplateAt("0", Indentation.Standard,
`/**
*
*/`);
verify.docCommentTemplateAt("0", singleLineOffset,
"/** */");
verify.docCommentTemplateAt("1", Indentation.Indented,
`/**
*
*/`);
verify.docCommentTemplateAt("1", singleLineOffset,
"/** */");
verify.docCommentTemplateAt("2", Indentation.Indented,
verify.docCommentTemplateAt("2", multiLineOffset,
`/**
*
* @param a
*/
`);
verify.docCommentTemplateAt("3", Indentation.Indented,
verify.docCommentTemplateAt("3", multiLineOffset,
`/**
*
* @param a
@ -43,7 +37,7 @@ verify.docCommentTemplateAt("3", Indentation.Indented,
*/
`);
verify.docCommentTemplateAt("4", Indentation.Indented,
verify.docCommentTemplateAt("4", multiLineOffset,
`/**
*
* @param a
@ -51,7 +45,7 @@ verify.docCommentTemplateAt("4", Indentation.Indented,
* @param param2
*/`);
verify.docCommentTemplateAt("5", Indentation.Indented,
verify.docCommentTemplateAt("5", multiLineOffset,
`/**
*
* @param a

13
tests/cases/fourslash/docCommentTemplateClassDeclMethods02.ts
View File

@ -1,8 +1,7 @@
/// <reference path='fourslash.ts' />
const enum Indentation {
Indented = 12,
}
const singleLineOffset = 3;
const multiLineOffset = 12;
////class C {
//// /*0*/
@ -13,12 +12,10 @@ const enum Indentation {
//// [1 + 2 + 3 + Math.rand()](x: number, y: string, z = true) { }
////}
verify.docCommentTemplateAt("0", Indentation.Indented,
`/**
*
*/`);
verify.docCommentTemplateAt("0", singleLineOffset,
"/** */");
verify.docCommentTemplateAt("1", Indentation.Indented,
verify.docCommentTemplateAt("1", multiLineOffset,
`/**
*
* @param x

2
tests/cases/fourslash/docCommentTemplateEmptyFile.ts
View File

@ -3,4 +3,4 @@
// @Filename: emptyFile.ts
/////*0*/
verify.noDocCommentTemplateAt("0");
verify.docCommentTemplateAt("0", 3, "/** */");

13
tests/cases/fourslash/docCommentTemplateIndentation.ts
View File

@ -5,13 +5,8 @@
//// /*1*/
/////*0*/ function foo() { }
const noIndentEmptyScaffolding = "/**\r\n * \r\n */";
const oneIndentEmptyScaffolding = "/**\r\n * \r\n */";
const twoIndentEmptyScaffolding = "/**\r\n * \r\n */";
const noIndentOffset = 8;
const oneIndentOffset = noIndentOffset + 4;
const twoIndentOffset = oneIndentOffset + 4;
const singleLineComment = "/** */";
verify.docCommentTemplateAt("0", noIndentOffset, noIndentEmptyScaffolding);
verify.docCommentTemplateAt("1", oneIndentOffset, oneIndentEmptyScaffolding);
verify.docCommentTemplateAt("2", twoIndentOffset, twoIndentEmptyScaffolding);
verify.docCommentTemplateAt("0", 3, singleLineComment);
verify.docCommentTemplateAt("1", 3, singleLineComment);
verify.docCommentTemplateAt("2", 3, singleLineComment);

10
tests/cases/fourslash/docCommentTemplateInsideFunctionDeclaration.ts
View File

@ -3,6 +3,10 @@
// @Filename: functionDecl.ts
////f/*0*/unction /*1*/foo/*2*/(/*3*/) /*4*/{ /*5*/}
for (const marker of test.markers()) {
verify.noDocCommentTemplateAt(marker);
}
verify.noDocCommentTemplateAt("0");
verify.docCommentTemplateAt("1", 3, "/** */");
verify.docCommentTemplateAt("2", 3, "/** */");
verify.docCommentTemplateAt("3", 3, "/** */");
verify.docCommentTemplateAt("4", 3, "/** */");
verify.docCommentTemplateAt("5", 3, "/** */");

49
tests/cases/fourslash/docCommentTemplateInterfacesEnumsAndTypeAliases.ts Normal file
View File

@ -0,0 +1,49 @@
/// <reference path='fourslash.ts' />
/////*interfaceFoo*/
////interface Foo {
//// /*propertybar*/
//// bar: any;
////
//// /*methodbaz*/
//// baz(message: any): void;
////
//// /*methodUnit*/
//// unit(): void;
////}
////
/////*enumStatus*/
////const enum Status {
//// /*memberOpen*/
//// Open,
////
//// /*memberClosed*/
//// Closed
////}
////
/////*aliasBar*/
////type Bar = Foo & any;
verify.docCommentTemplateAt("interfaceFoo", /*expectedOffset*/ 3,
"/** */");
verify.docCommentTemplateAt("propertybar", /*expectedOffset*/ 3,
"/** */");
verify.docCommentTemplateAt("methodbaz", /*expectedOffset*/ 12,
`/**
*
* @param message
*/`);
verify.docCommentTemplateAt("methodUnit", /*expectedOffset*/ 3,
"/** */");
verify.docCommentTemplateAt("enumStatus", /*expectedOffset*/ 3,
"/** */");
verify.docCommentTemplateAt("memberOpen", /*expectedOffset*/ 3,
"/** */");
verify.docCommentTemplateAt("memberClosed", /*expectedOffset*/ 3,
"/** */");

12
tests/cases/fourslash/docCommentTemplateJSXText.ts Normal file
View File

@ -0,0 +1,12 @@
/// <reference path="fourslash.ts" />
//@Filename: file.tsx
////
//// var x = <div>
//// /*0*/hello/*1*/
//// /*2*/goodbye/*3*/
//// </div>;
for (const marker in test.markers()) {
verify.noDocCommentTemplateAt(marker);
}

18
tests/cases/fourslash/docCommentTemplateNamespacesAndModules01.ts
View File

@ -12,17 +12,11 @@
////module "ambientModule" {
////}
verify.docCommentTemplateAt("namespaceN", /*indentation*/ 8,
`/**
*
*/`);
verify.docCommentTemplateAt("namespaceN", /*indentation*/ 3,
"/** */");
verify.docCommentTemplateAt("namespaceM", /*indentation*/ 8,
`/**
*
*/`);
verify.docCommentTemplateAt("namespaceM", /*indentation*/ 3,
"/** */");
verify.docCommentTemplateAt("namespaceM", /*indentation*/ 8,
`/**
*
*/`);
verify.docCommentTemplateAt("namespaceM", /*indentation*/ 3,
"/** */");

10
tests/cases/fourslash/docCommentTemplateNamespacesAndModules02.ts
View File

@ -6,11 +6,9 @@
//// /*n3*/ n3 {
////}
verify.docCommentTemplateAt("top", /*indentation*/ 8,
`/**
*
*/`);
verify.docCommentTemplateAt("top", /*indentation*/ 3,
"/** */");
verify.noDocCommentTemplateAt("n2");
verify.docCommentTemplateAt("n2", 3, "/** */");
verify.noDocCommentTemplateAt("n3");
verify.docCommentTemplateAt("n3", 3, "/** */");

13
tests/cases/fourslash/docCommentTemplateObjectLiteralMethods01.ts
View File

@ -1,8 +1,7 @@
/// <reference path='fourslash.ts' />
const enum Indentation {
Indented = 12,
}
const singleLineOffset = 3;
const multiLineOffset = 12;
////var x = {
//// /*0*/
@ -13,12 +12,10 @@ const enum Indentation {
//// [1 + 2 + 3 + Math.rand()](x: number, y: string, z = true) { }
////}
verify.docCommentTemplateAt("0", Indentation.Indented,
`/**
*
*/`);
verify.docCommentTemplateAt("0", singleLineOffset,
"/** */");
verify.docCommentTemplateAt("1", Indentation.Indented,
verify.docCommentTemplateAt("1", multiLineOffset,
`/**
*
* @param x

8
tests/cases/fourslash/docCommentTemplateRegex.ts
View File

@ -3,6 +3,8 @@
// @Filename: regex.ts
////var regex = /*0*///*1*/asdf/*2*/ /*3*///*4*/;
for (const marker of test.markers()) {
verify.noDocCommentTemplateAt(marker);
}
verify.docCommentTemplateAt("0", 3, "/** */");
verify.noDocCommentTemplateAt("1");
verify.noDocCommentTemplateAt("2");
verify.noDocCommentTemplateAt("3");
verify.docCommentTemplateAt("4", 3, "/** */");

6
tests/cases/fourslash/docCommentTemplateVariableStatements01.ts
View File

@ -29,10 +29,8 @@
////}
for (const varName of ["a", "b", "c", "d"]) {
verify.docCommentTemplateAt(varName, /*newTextOffset*/ 8,
`/**
*
*/`);
verify.docCommentTemplateAt(varName, /*newTextOffset*/ 3,
"/** */");
}
verify.docCommentTemplateAt("e", /*newTextOffset*/ 8,

6
tests/cases/fourslash/docCommentTemplateVariableStatements02.ts
View File

@ -29,8 +29,6 @@
////}, f2 = null;
for (const varName of ["a", "b", "c", "d", "e", "f"]) {
verify.docCommentTemplateAt(varName, /*newTextOffset*/ 8,
`/**
*
*/`);
verify.docCommentTemplateAt(varName, /*newTextOffset*/ 3,
"/** */");
}

12
tests/cases/fourslash/docCommentTemplateVariableStatements03.ts
View File

@ -49,10 +49,8 @@ verify.docCommentTemplateAt("c", /*newTextOffset*/ 8,
* @param x
*/`);
verify.docCommentTemplateAt("d", /*newTextOffset*/ 8,
`/**
*
*/`);
verify.docCommentTemplateAt("d", /*newTextOffset*/ 3,
"/** */");
verify.docCommentTemplateAt("e", /*newTextOffset*/ 8,
`/**
@ -60,10 +58,8 @@ verify.docCommentTemplateAt("e", /*newTextOffset*/ 8,
* @param param0
*/`);
verify.docCommentTemplateAt("f", /*newTextOffset*/ 8,
`/**
*
*/`);
verify.docCommentTemplateAt("f", /*newTextOffset*/ 3,
"/** */");
verify.docCommentTemplateAt("g", /*newTextOffset*/ 8,
`/**