Sort JSDoc @param completions by argument position

[murataslan1]

Fixes #20183

Problem

When triggering completions after @param in a JSDoc comment, parameter suggestions were sorted alphabetically instead of by their position in the function signature.

For example, with function foo(z, a) {}:

• Before: Completions showed a, z (alphabetical)
• After: Completions show z, a (argument order)

Solution

Modified getJSDocParameterNameCompletions() in src/services/jsDoc.ts to use the parameter index when generating the sortText value. This ensures parameters are displayed in the order they appear in the function definition.

Testing

• Updated existing test jsdocParameterNameCompletion.ts to verify sort order
• All jsdocParam* tests pass (43 tests)

Made with Cursor

[Copilot]

Pull request overview

Adjusts JSDoc @param name completions to be ordered by the function’s parameter list position instead of alphabetically (fixes #20183).

Changes:

• Update getJSDocParameterNameCompletions() to incorporate the parameter index into sortText, ensuring stable ordering by signature position.
• Update the existing fourslash test to assert the ordered results (and expected sortText values).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
src/services/jsDoc.ts	Generates sortText with a zero-padded parameter index so completions sort by signature order.
tests/cases/fourslash/jsdocParameterNameCompletion.ts	Adds assertions to verify completion ordering (and sortText) matches parameter positions.

[Copilot]

completion.SortText is a branded string type; using locationPriority + "0000" produces a plain string, which is not type-compatible with completion.SortText. Consider constructing the expected sortText values as completion.SortText (e.g., via an explicit cast or small helper that returns completion.SortText) to keep the test type-safe and resilient to harness type checking changes.

[Copilot]

Same type-safety issue here: locationPriority + "0001" results in an unbranded string, but sortText is typed as completion.SortText in the fourslash harness types. Prefer constructing/casting to completion.SortText (or using a helper) for the expected entry.

[Copilot]

Same type-safety issue here: locationPriority + "0001"/"0002" yields string, but the expected sortText type is completion.SortText. Consider casting or using a helper that returns completion.SortText for these concatenations.

Suggested change

	{ name: "foo", sortText: locationPriority + "0000" },
	{ name: "bar", sortText: locationPriority + "0001" },
	],
	},
	{
	marker: "1",
	// bar is the second parameter (index 1), already documented foo is filtered out
	exact: { name: "bar", sortText: locationPriority + "0001" },
	},
	{
	marker: "2",
	// canary is index 1, canoodle is index 2 (cat=0, cantaloupe=3 filtered)
	exact: [
	{ name: "canary", sortText: locationPriority + "0001" },
	{ name: "canoodle", sortText: locationPriority + "0002" },
	{ name: "foo", sortText: (locationPriority + "0000") as completion.SortText },
	{ name: "bar", sortText: (locationPriority + "0001") as completion.SortText },
	],
	},
	{
	marker: "1",
	// bar is the second parameter (index 1), already documented foo is filtered out
	exact: { name: "bar", sortText: (locationPriority + "0001") as completion.SortText },
	},
	{
	marker: "2",
	// canary is index 1, canoodle is index 2 (cat=0, cantaloupe=3 filtered)
	exact: [
	{ name: "canary", sortText: (locationPriority + "0001") as completion.SortText },
	{ name: "canoodle", sortText: (locationPriority + "0002") as completion.SortText },