Skip to content

Commit 03b036b

Browse files
uniqueiniquityuniqueiniquity
committed
Revert "Loosen restrictions on jsdoc completion locations"
This reverts commit 612616a.
1 parent d3a7db8 commit 03b036b

6 files changed

Lines changed: 53 additions & 51 deletions

‎src/services/jsDoc.ts‎

Lines changed: 44 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
/* @internal */
22
namespace ts.JsDoc {
3-
const singleLineTemplate = { newText: "/** */", caretOffset: 3 };
43
const jsDocTagNames = [
54
"augments",
65
"author",
@@ -197,9 +196,15 @@ namespace ts.JsDoc {
197196
/**
198197
* Checks if position points to a valid position to add JSDoc comments, and if so,
199198
* returns the appropriate template. Otherwise returns an empty string.
200-
* Invalid positions are
201-
* - within comments, strings (including template literals and regex), and JSXText
202-
* - within a token
199+
* Valid positions are
200+
* - outside of comments, statements, and expressions, and
201+
* - preceding a:
202+
* - function/constructor/method declaration
203+
* - class declarations
204+
* - variable statements
205+
* - namespace declarations
206+
* - interface declarations
207+
* - method signatures
203208
*
204209
* Hosts should ideally check that:
205210
* - The line is all whitespace up to 'position' before performing the insertion.
@@ -225,19 +230,17 @@ namespace ts.JsDoc {
225230

226231
const commentOwnerInfo = getCommentOwnerInfo(tokenAtPos);
227232
if (!commentOwnerInfo) {
228-
// if climbing the tree did not find a declaration with parameters, complete to a single line comment
229-
return singleLineTemplate;
233+
return undefined;
230234
}
231235
const { commentOwner, parameters } = commentOwnerInfo;
232-
233-
if (commentOwner.kind === SyntaxKind.JsxText) {
236+
if (commentOwner.getStart() < position) {
234237
return undefined;
235238
}
236239

237-
if (commentOwner.getStart() < position || parameters.length === 0) {
238-
// if climbing the tree found a declaration with parameters but the request was made inside it
239-
// or if there are no parameters, complete to a single line comment
240-
return singleLineTemplate;
240+
if (!parameters || parameters.length === 0) {
241+
// if there are no parameters, just complete to a single line JSDoc comment
242+
const singleLineResult = "/** */";
243+
return { newText: singleLineResult, caretOffset: 3 };
241244
}
242245

243246
const posLineAndChar = sourceFile.getLineAndCharacterOfPosition(position);
@@ -247,11 +250,19 @@ namespace ts.JsDoc {
247250
const indentationStr = sourceFile.text.substr(lineStart, posLineAndChar.character).replace(/\S/i, () => " ");
248251
const isJavaScriptFile = hasJavaScriptFileExtension(sourceFile.fileName);
249252

250-
const docParams = parameters.map(({name}, i) => {
251-
const nameText = isIdentifier(name) ? name.text : `param${i}`;
252-
const type = isJavaScriptFile ? "{any} " : "";
253-
return `${indentationStr} * @param ${type}${nameText}${newLine}`;
254-
}).join("");
253+
let docParams = "";
254+
for (let i = 0; i < parameters.length; i++) {
255+
const currentName = parameters[i].name;
256+
const paramName = currentName.kind === SyntaxKind.Identifier ?
257+
(<Identifier>currentName).escapedText :
258+
"param" + i;
259+
if (isJavaScriptFile) {
260+
docParams += `${indentationStr} * @param {any} ${paramName}${newLine}`;
261+
}
262+
else {
263+
docParams += `${indentationStr} * @param ${paramName}${newLine}`;
264+
}
265+
}
255266

256267
// A doc comment consists of the following
257268
// * The opening comment line
@@ -273,7 +284,7 @@ namespace ts.JsDoc {
273284

274285
interface CommentOwnerInfo {
275286
readonly commentOwner: Node;
276-
readonly parameters: ReadonlyArray<ParameterDeclaration>;
287+
readonly parameters?: ReadonlyArray<ParameterDeclaration>;
277288
}
278289
function getCommentOwnerInfo(tokenAtPos: Node): CommentOwnerInfo | undefined {
279290
for (let commentOwner = tokenAtPos; commentOwner; commentOwner = commentOwner.parent) {
@@ -285,18 +296,32 @@ namespace ts.JsDoc {
285296
const { parameters } = commentOwner as FunctionDeclaration | MethodDeclaration | ConstructorDeclaration | MethodSignature;
286297
return { commentOwner, parameters };
287298

299+
case SyntaxKind.ClassDeclaration:
300+
case SyntaxKind.InterfaceDeclaration:
301+
case SyntaxKind.PropertySignature:
302+
case SyntaxKind.EnumDeclaration:
303+
case SyntaxKind.EnumMember:
304+
case SyntaxKind.TypeAliasDeclaration:
305+
return { commentOwner };
306+
288307
case SyntaxKind.VariableStatement: {
289308
const varStatement = <VariableStatement>commentOwner;
290309
const varDeclarations = varStatement.declarationList.declarations;
291310
const parameters = varDeclarations.length === 1 && varDeclarations[0].initializer
292311
? getParametersFromRightHandSideOfAssignment(varDeclarations[0].initializer)
293312
: undefined;
294-
return parameters ? { commentOwner, parameters } : undefined;
313+
return { commentOwner, parameters };
295314
}
296315

297316
case SyntaxKind.SourceFile:
298317
return undefined;
299318

319+
case SyntaxKind.ModuleDeclaration:
320+
// If in walking up the tree, we hit a a nested namespace declaration,
321+
// then we must be somewhere within a dotted namespace name; however we don't
322+
// want to give back a JSDoc template for the 'b' or 'c' in 'namespace a.b.c { }'.
323+
return commentOwner.parent.kind === SyntaxKind.ModuleDeclaration ? undefined : { commentOwner };
324+
300325
case SyntaxKind.BinaryExpression: {
301326
const be = commentOwner as BinaryExpression;
302327
if (getSpecialPropertyAssignmentKind(be) === ts.SpecialPropertyAssignmentKind.None) {
@@ -305,11 +330,6 @@ namespace ts.JsDoc {
305330
const parameters = isFunctionLike(be.right) ? be.right.parameters : emptyArray;
306331
return { commentOwner, parameters };
307332
}
308-
309-
case SyntaxKind.JsxText: {
310-
const parameters: ReadonlyArray<ParameterDeclaration> = emptyArray;
311-
return { commentOwner, parameters };
312-
}
313333
}
314334
}
315335
}

‎tests/cases/fourslash/docCommentTemplateEmptyFile.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,4 @@
33
// @Filename: emptyFile.ts
44
/////*0*/
55

6-
verify.docCommentTemplateAt("0", 3, "/** */");
6+
verify.noDocCommentTemplateAt("0");

‎tests/cases/fourslash/docCommentTemplateInsideFunctionDeclaration.ts‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,6 @@
33
// @Filename: functionDecl.ts
44
////f/*0*/unction /*1*/foo/*2*/(/*3*/) /*4*/{ /*5*/}
55

6-
verify.noDocCommentTemplateAt("0");
7-
8-
verify.docCommentTemplateAt("1", 3, "/** */");
9-
verify.docCommentTemplateAt("2", 3, "/** */");
10-
verify.docCommentTemplateAt("3", 3, "/** */");
11-
verify.docCommentTemplateAt("4", 3, "/** */");
12-
verify.docCommentTemplateAt("5", 3, "/** */");
6+
for (const marker of test.markers()) {
7+
verify.noDocCommentTemplateAt(marker);
8+
}

‎tests/cases/fourslash/docCommentTemplateJSXText.ts‎

Lines changed: 0 additions & 12 deletions
This file was deleted.

‎tests/cases/fourslash/docCommentTemplateNamespacesAndModules02.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,6 @@
99
verify.docCommentTemplateAt("top", /*indentation*/ 3,
1010
"/** */");
1111

12-
verify.docCommentTemplateAt("n2", 3, "/** */");
12+
verify.noDocCommentTemplateAt("n2");
1313

14-
verify.docCommentTemplateAt("n3", 3, "/** */");
14+
verify.noDocCommentTemplateAt("n3");

‎tests/cases/fourslash/docCommentTemplateRegex.ts‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,6 @@
33
// @Filename: regex.ts
44
////var regex = /*0*///*1*/asdf/*2*/ /*3*///*4*/;
55

6-
verify.docCommentTemplateAt("0", 3, "/** */");
7-
verify.noDocCommentTemplateAt("1");
8-
verify.noDocCommentTemplateAt("2");
9-
verify.noDocCommentTemplateAt("3");
10-
verify.docCommentTemplateAt("4", 3, "/** */");
6+
for (const marker of test.markers()) {
7+
verify.noDocCommentTemplateAt(marker);
8+
}

0 commit comments

Comments
 (0)