Transform descriptions and examples into TSDoc comments

[bbenoist]

It would be nice to have an option to add TSDoc comments alongside the generated code.

(TSDoc is supported natively by editors such as VSCode)

Example:

/**
 * Some description extracted from OpenAPI spec
 * @param petId - Params are in the OpenAPI specs too
 * @param opts - We could use {@link RequestOpts} to redirect to objects documentation
 * @returns Why not also use {@link ReturnType} in this section?
 * @remarks
 * Not sure whether there is something to add here...
 * @examples
 * We could add some usage examples and use the values from the OpenAPI spec examples:
 * ```ts
 * const res = await api.getPetById(1);
 * if (res.status === 200) {
 *   const pet = res.data;
 *   // pet is properly typed as Pet
 * }
 * if (res.status === 404) {
 *   const message = res.data;
 *   // message is a string
 * } else {
 *   // handle the error
 * }
 * ```
 * @deprecated
 * @public
 */
export function getPetById(petId: number, opts?: RequestOpts) {
// ...
}

⚠️ A useful addition would be to also support the api-extractor @deprecated, and @public release tags (with an option to use @internal instead of @public) so that we could use it to generate some API documentation with compatible tools such as api-documenter

[gaggle]

I came here to ask the same. Does it sound like a huge undertaking? I could take a look at it, but could use some pointers to get started 😬

[Xiphe]

Especially the @deprecated part should not be too complicated and make it more easy to find outdated usages in the codebase because VSCode for example strikes them

[ehvattum]

This feature would indeed be immensely useful.