How can one point to a parameter within the documentation of a TypeScript function?

Question

How can one point to a parameter within the documentation of a TypeScript function?

I am attempting to incorporate parameter references in function descriptions 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<{}> { [...] }

Unfortunately, it seems that using {@param id} does not yield the desired result. When invoking the function, the output is as follows:

(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 would like to have a clickable element in the documentation that links to the parameter (within the function's general description, rather than within the parameter description). Is there a correct way to reference a parameter or even the return value of a function in the description? (I am utilizing Visual Studio Code).

typescript jsdoc

Answer 1

Answer №1

April 2023, VSCode version 1.73.1

{@link paramname} is presented as a clickable link in the annotation popup of VSCode. Clicking on it will navigate to the referenced parameter.

Here is an example showcasing the use of @returns tag with @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 the 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 documentation popup in VSCode appears as follows: https://i.sstatic.net/rKOm8.png

Answer 2

April 2023, VSCode version 1.73.1

{@link paramname} is presented as a clickable link in the annotation popup of VSCode. Clicking on it will navigate to the referenced parameter.

Here is an example showcasing the use of @returns tag with @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 the 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 documentation popup in VSCode appears as follows: https://i.sstatic.net/rKOm8.png

Answer 3

Answer №2

according to the advice from @basarat, it is not possible to directly reference a parameter within documentation itself. However, one option that comes close is using the @link and @see directives.

// this `id` const is used only when there's no @param id in the documentation
const id: number = 33 // or any other value
/**
 * Removes the Travel Expense with the specified {@link id}
 * @param id the identifier of the travel cost to be removed
 */
deleteTravelCost(id: number): Observable<{}> { [...] }

Answer 4

according to the advice from @basarat, it is not possible to directly reference a parameter within documentation itself. However, one option that comes close is using the @link and @see directives.

// this `id` const is used only when there's no @param id in the documentation
const id: number = 33 // or any other value
/**
 * Removes the Travel Expense with the specified {@link id}
 * @param id the identifier of the travel cost to be removed
 */
deleteTravelCost(id: number): Observable<{}> { [...] }

Answer 5

Answer №3

Is it possible to correctly reference a parameter?

Unfortunately, you cannot create cross-references for parameters. Refer to this link for more information: https://github.com/jsdoc/jsdoc/issues/1145#issue-126426000

How to include the return of a function in the description?

Once again, referencing the return value is not supported. However, you can document it using the 'returns' tag. Here's an example:

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

Answer 6

Is it possible to correctly reference a parameter?

Unfortunately, you cannot create cross-references for parameters. Refer to this link for more information: https://github.com/jsdoc/jsdoc/issues/1145#issue-126426000

How to include the return of a function in the description?

Once again, referencing the return value is not supported. However, you can document it using the 'returns' tag. Here's an example:

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

How can one point to a parameter within the documentation of a TypeScript function?

Answer №1

Answer №2

Answer №3

Similar questions

Tips for resolving type checking errors in TypeScript and React

Is there a way to define an interface that consists of child objects as the type for a function that uses destructured props?

Leverage the extended properties of Express.js's Request's generic arguments

Leveraging Global Variables in TypeScript with Node Express

Invoking the callback function within the containing scope in Typescript

What is the best way to specify a function parameter as the `QUnit` type using TypeScript in conjunction with QUnit?

Loading the value of a Subject variable in an Angular 2 application using Typescript

Find the combined key names in an object where the values can be accessed by index

Learn how to selectively hide the header from the root layout on a single page in Next.js version 14

Continuously extract information by filtering through the array

Hold off on proceeding until the subscription loop has finished

Issue encountered while setting up controls and AbstractControls in form development

Tips on preventing the copying of .txt and .xml files with the fs-extra.copySync function

Learn the process of setting up a connection between Express JS and the NotionAPI using both POST and

What specific event do I require for the onChange event in React using TypeScript?

What is the best way to retrieve and showcase data in NextJs version 13 and beyond?

Is it possible to integrate TypeScript 5.0 decorators into React components?

In a Typescript Next Js project, the useReducer Hook cannot be utilized

Determining the name of the currently focused DOM element in Angular2

Can we verify the availability of an Angular library during runtime?