Order JSDoc @param name completions by declaration order

src/services/jsDoc.ts

@@ -68,7 +68,6 @@ import {
     length,
     lineBreakPart,
     map,
-    mapDefined,
     MethodDeclaration,
     MethodSignature,
     Node,
@@ -420,19 +419,21 @@ export function getJSDocParameterNameCompletions(tag: JSDocParameterTag): Comple
     const fn = jsdoc.parent;
     if (!isFunctionLike(fn)) return [];
 
-    return mapDefined(fn.parameters, param => {
-        if (!isIdentifier(param.name)) return undefined;
+    const entries: CompletionEntry[] = [];
+    for (const param of fn.parameters) {
+        if (!isIdentifier(param.name)) continue;
 
         const name = param.name.text;
         if (
             jsdoc.tags!.some(t => t !== tag && isJSDocParameterTag(t) && isIdentifier(t.name) && t.name.escapedText === name) // TODO: GH#18217
             || nameThusFar !== undefined && !startsWith(name, nameThusFar)
         ) {
-            return undefined;
+            continue;
         }
 
-        return { name, kind: ScriptElementKind.parameterElement, kindModifiers: "", sortText: Completions.SortText.LocationPriority };
-    });
+        entries.push({ name, kind: ScriptElementKind.parameterElement, kindModifiers: "", sortText: Completions.SortText.LocationPriority });
+    }
+    return entries;
 }
 
 /** @internal */

tests/cases/fourslash/jsDocParamCompletion_filterAlreadyDocumented.ts

@@ -0,0 +1,12 @@
+/// <reference path="fourslash.ts" />
+
+// Expectation: Only 'a' is suggested because 'z' is already documented.
+//// /**
+////  * @param z
+////  * @param /*1*/
+////  */
+//// function foo(z: number, a: number) {}
+
+verify.completions({ marker: "1", exact: ["a"] });
+
+

tests/cases/fourslash/jsDocParamCompletion_jsFile.ts

@@ -0,0 +1,14 @@
+/// <reference path="fourslash.ts" />
+// @allowJs: true
+// @Filename: a.js
+
+// Expectation (JS): Declaration order is preserved: 'z' before 'a'.
+//// /**
+////  * @param /*1*/
+////  */
+//// function foo(z, a) {}
+
+goTo.file("a.js");
+verify.completions({ marker: "1", exact: ["z", "a"] });
+
+

tests/cases/fourslash/jsDocParamCompletion_optionalAndRest.ts

@@ -0,0 +1,11 @@
+/// <reference path="fourslash.ts" />
+
+// Expectation: Declaration order is preserved: 'a' (optional) before 'z' (rest).
+//// /**
+////  * @param /*1*/
+////  */
+//// function foo(a?: number, ...z: number[]) {}
+
+verify.completions({ marker: "1", exact: ["a", "z"] });
+
+

tests/cases/fourslash/jsDocParamCompletion_order.ts

@@ -0,0 +1,16 @@
+/// <reference path="fourslash.ts" />
+
+//// /**
+////  * @param /*1*/
+////  */
+//// function foo(z: number, a: number) {}
+
+verify.completions({
+    marker: "1",
+    exact: ["z", "a"], // expected: declaration order
+  });
+
+  /**
+ * @param |
+ */
+function foo(z: number, a: number) {}

tests/cases/fourslash/jsDocParamCompletion_overloadsUseImplementation.ts

@@ -0,0 +1,12 @@
+/// <reference path="fourslash.ts" />
+
+// Expectation: Suggestions are based on the implementation signature: 'a', then 'z'.
+//// /**
+////  * @param /*1*/
+////  */
+//// function foo(a: number, z: number): void;
+//// function foo(a: number, z: number): void {}
+
+verify.completions({ marker: "1", exact: ["a", "z"] });
+
+

tests/cases/fourslash/jsDocParamCompletion_prefixFiltering.ts

@@ -0,0 +1,11 @@
+/// <reference path="fourslash.ts" />
+
+// Expectation: Only 'a' is suggested due to prefix filtering after '@param a'.
+//// /**
+////  * @param a/*1*/
+////  */
+//// function foo(z: number, a: number) {}
+
+verify.completions({ marker: "1", exact: ["a"] });
+
+

tests/cases/fourslash/jsDocParamCompletion_skipDestructured.ts

@@ -0,0 +1,11 @@
+/// <reference path="fourslash.ts" />
+
+// Expectation: Destructured parameter is skipped; only identifier param 'z' is suggested.
+//// /**
+////  * @param /*1*/
+////  */
+//// function foo({ x }: any, z: number) {}
+
+verify.completions({ marker: "1", exact: ["z"] });
+
+