Typescript: Are there any conventions to document code with comments?

Question

I am used to document code in our C# projects in a specific way to enhance team productivity, benefit from Intellisense in Visual Studio etc.

Code looks similar to this:

/// <summary>
/// Loads a user with a specific id.
/// </summary>
/// <param name="id">The id of the user to search for.</param>
/// <returns>A user with the given id.</returns>
public User GetUserById(string id) {
    ...
}

Are there any similar conventions for Typescript for commenting and documentation? Or even tools that use these conventions to generate documentation pages in html from code comments (like JavaDoc)?

Answer 1

Yes there are.

Most common used comment conventions (to no surprise) comes from javascript in form of jsdoc. For example VSCode support them out of the box. Also there are some tools specifically developed for typescript doc generation like typedoc

Answer 2

TSDoc is the latest proposed convention for commenting and documentation of Typescript source file. Its notation looks as follows -

/**
 * Returns the average of two numbers.
 *
 * @remarks
 * This method is part of the {@link core-library#Statistics | Statistics subsystem}.
 *
 * @param x - The first input number
 * @param y - The second input number
 * @returns The arithmetic mean of `x` and `y`
 */
function getAverage(x: number, y: number): number {
  return (x + y) / 2.0;
}

TypeDoc tool can parse comments in this convention & generates documentation pages in HTML.