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

user_8924119 0
Viewed 413

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).

typescript jsdoc
2 Answers

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;
}
user_3903300

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<{}> { [...] }
user_197976100
Related