CODEWITHSUNDEEP
c#typescriptdocumentationcommentsconventions
Michael Hilus
Michael Hilus

Reputation: 1828

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

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

Upvotes: 12

Views: 15198

Answers (2)

Amid
Amid

Reputation: 22322

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

Upvotes: 12

Mohit Khandelwal
Mohit Khandelwal

Reputation: 651

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.

Upvotes: 13

Related Questions