Where is the syntax for TypeScript comments documented?

Question

Is the syntax for TypeScript comments documented anywhere?

And by any chance, does it now support the C# /// system?

Borges

Answer 1

Update November 2020

A website is now online with all the TSDoc syntax available (and that's awesome): https://tsdoc.org/

---

For reference, old answer:

The right syntax is now the one used by TSDoc. It will allow you to have your comments understood by Visual Studio Code or other documentation tools.

A good overview of the syntax is available here and especially here. The precise spec should be "soon" written up.

Another file worth checking out is this one where you will see useful standard tags.

Note: you should not use JSDoc, as explained on TSDoc main page: Why can't JSDoc be the standard? Unfortunately, the JSDoc grammar is not rigorously specified but rather inferred from the behavior of a particular implementation. The majority of the standard JSDoc tags are preoccupied with providing type annotations for plain JavaScript, which is an irrelevant concern for a strongly-typed language such as TypeScript. TSDoc addresses these limitations while also tackling a more sophisticated set of goals.

Subsonic

Answer 2

Current

The TypeScript team, and other TypeScript involved teams, created a TSDoc specification. https://tsdoc.org/

Example straight from the docs:

export class Statistics {
  /**
   * 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`
   *
   * @beta
   */
  public static getAverage(x: number, y: number): number {
    return (x + y) / 2.0;
  }
}

Past

TypeScript uses JSDoc. e.g.

/** This is a description of the foo function. */
function foo() {
}

To learn jsdoc : https://jsdoc.app/

But you don't need to use the type annotation extensions in JSDoc.

You can (and should) still use other jsdoc block tags like @returns etc.

Just an example. Focus on the types (not the content).

JSDoc version (notice types in docs):

/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function sum(a, b) {
    return a + b;
}

TypeScript version (notice the re-location of types):

/**
 * Takes two numbers and returns their sum
 * @param a first input to sum
 * @param b second input to sum
 * @returns sum of a and b
 */
function sum(a: number, b: number): number {
    return a + b;
}

Assyrian

As Bas says! For a good example of usage check out the DefinitelyTyped's jQuery.d.ts – Kef

which of course got jsdoc'ed by @JohnnyReilly! :) github.com/borisyankov/DefinitelyTyped/blame/master/jquery/… – Assyrian

Too right! But would seem immodest to draw attention to that :-) – Kef

This is not a good "best answer" as it doesn't explain parameters, properties and return values. – Anet

@Assyrian link is broken now :/ – Arst

As this answer comes first in the web searches, I'd like to contribute on how add parameters: Below the main description, add this line: @param parameterName description. The spaces are the separators. – Cutthroat

Updated link: github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/… – Starryeyed

Note that the double asterisk at the beginning of the comment is not a typo. writing a c style comment is acceptable for JS, but it will not be used as a JSDoc comment. (Why /** foo / and not /* foo **/ is beyond me though....) – Gough

This is no longer up to date. See updated answer below. – Subsonic

There are some limitations of supported annotations: typescriptlang.org/docs/handbook/jsdoc-supported-types.html – Koziel

Thanks Simon. That link only shows the type annotations section of jsdoc and personally I don't recommend using any type annotations from jsdoc. For types use the standard TS Syntax 🌹 – Assyrian

@Subsonic Thanks. Not quite out of date yet. But yeah will get there 🌹 – Assyrian

Just wanted to add that you can specify the type of a single parameter, inline, like this: function MyFunc(/** @type {string} */ myStringParam) {} – Embolus

Params not explained @Anet is 100% right – Sakti

is there a way to "trigger" the creation of the comment structure for the method? just like typing /// in Visual Studio for c#? – Advisee

Answer 3

You can add information about parameters, returns, etc. as well using:

/**
* This is the foo function
* @param bar This is the bar parameter
* @returns returns a string version of bar
*/
function foo(bar: number): string {
    return bar.toString()
}

This will cause editors like VS Code to display it as the following:

Pacificia

Do u know the shortcut key for this in VSCODE – Carri

If you start typing /** then press tab on a line above the function, vs-code assists you in filling out the JSDoc comment with parameters – Pacificia

Isn't the second returns redundant? E.g. @returns returns a string... vs @returns a string... – Modulation

Answer 4

You can use comments like in regular JavaScript:

1 Introduction

[...] TypeScript syntax is a superset of ECMAScript 2015 (ES2015) syntax.

2 Basic Concepts

[...] This document describes the syntactic grammar added by TypeScript [...]

Source: TypeScript Language Specification

---

The only two mentions of the word "comments" in the spec are:

1 Introduction

[...] TypeScript also provides to JavaScript programmers a system of optional type annotations. These type annotations are like the JSDoc comments found in the Closure system, but in TypeScript they are integrated directly into the language syntax. This integration makes the code more readable and reduces the maintenance cost of synchronizing type annotations with their corresponding variables.

11.1.1 Source Files Dependencies

[...] A comment of the form /// <reference path="..."/> adds a dependency on the source file specified in the path argument. The path is resolved relative to the directory of the containing source file.

Topper

All links are dead 😢 – Regression

@BernoulliIT Updated the links, but the spec is actually not maintained anymore: github.com/microsoft/TypeScript/pull/40373 – Topper

Answer 5

TypeScript is a strict syntactical superset of JavaScript hence

• Single line comments start with //
• Multi-line comments start with /* and end with */

Desmid