CODEWITHSUNDEEP
typescriptjsdoc
Joserbala
Joserbala

Reputation: 63

Is there a way to refer to a parameter in a TypeScript function documentation?

I'm trying to reference parameters in the description of functions like this:

/**
 * Deletes the Travel Cost with the given {@param id}
 * @param id the id of the travel cost to be deleted
 */
deleteTravelCost(id: number): Observable<{}> { [...] }

But it doesn't seem to work with the {@param id}. The result when invoking the function is the following:

(method) TravelCostsService.deleteTravelCost(id: number): Observable<{}>

Deletes the Travel Cost with the given {@param id}

@param id — the id of the travel cost to be deleted

I expect to have a clickable element in the documentation referencing to the parameter (in the general description of the function, not in the actual parameter description). Is there a proper way to reference a parameter or even the return of a function in the description? (I'm using Visual Studio Code).

Upvotes: 6

Views: 2399

Answers (3)

Ivan Akcheurov
Ivan Akcheurov

Reputation: 2373

April 2023, VSCode v1.73.1

{@link paramname} will be shown as a link in VSCode's annotation popup, upon clicking it would lead to the referenced parameter.

Example where @returns tag contains @link parameter references:

/**
 * Returns the original collection or filters it before returning
 * @param collection the collection to filter
 * @param filter if `false`, don't filter; otherwise the passed value is a predicate function and will be used for filtering
 * @returns the original {@link collection} with some or all of the original items depending on passed {@link filter}
 */
export function optionalFilter<T>(collection: T[], filter: ((value: T, index?: number, array?: T[]) => boolean) | false) {
    if (filter === false) {
        return collection;
    }
    return collection.filter(filter);
}

The VSCode documentation popup looks like this: enter image description here

Upvotes: 3

eslam sharif
eslam sharif

Reputation: 46

as @basarat said, there's no way to cross-reference a parameter within documentation itself, so the closest thing to that i can think of is @link and @see directives

// this `id` const is referenced only when there's no @param id in doc
const id: number = 33 // or anything
/**
 * Deletes the Travel Cost with the given {@link id}
 * @param id the id of the travel cost to be deleted
 */
deleteTravelCost(id: number): Observable<{}> { [...] }

Upvotes: 2

basarat
basarat

Reputation: 276293

is there a way to properly reference a parameter

You cannot cross reference parameters : https://github.com/jsdoc/jsdoc/issues/1145#issue-126426000

return of a function in the description

Again, you cannot reference it. But you can document it with returns e.g.: 

/**
 * Deletes the Travel Cost with the given 
 * @param id the id of the travel cost to be deleted
 * @returns the result
 */
function deleteTravelCost(id: number): number {
  return id;
}

Upvotes: 1

Related Questions