RFC: "@decorator" tag for documenting ECMAScript decorators

[octogonz]

ECMAScript decorators use syntax like this:

class Greeter {
  @format("Hello, %s")
  public greeting: string;

  public constructor(message: string) {
    this.greeting = message;
  }
  public greet(): string {
    let formatString = getFormat(this, "greeting");
    return formatString.replace("%s", this.greeting);
  }
}

Decorators are an experimental language feature (whose spec keeps getting rejected and reworked, and thus is not particularly stable yet). But they are heavily used in some frameworks such as Angular.

There's been a longstanding issue that API Extractor does not document them, because the TypeScript compiler does not emit decorator signatures in the .d.ts files. I asked about this a long time ago, and it was pointed out that decorators can involve arbitrarily complex runtime expressions (e.g. @format(x.map(y => f(y)).join('\n'))) that may be difficult to represent as a declaration.

Nonetheless, where decorators are used to define an API contract, that information really SHOULD be represented somehow in the .d.ts file. The .d.ts file is often the only description visible to consumers of the API. (For similar reasons API Extractor reads .d.ts files as its input -- it doesn't even consider the .ts files.)

Proposal

TSDoc provides a way that we can get the decorator signatures in the .d.ts files. It's a little clunky, but it's something we could implement easily today:

class Greeter {
  /** 
   * The text message returned by {@link Greeter.greet}.
   * @decorator `@format("Hello, %s")`
   */
  @format("Hello, %s")
  public greeting: string;

  public constructor(message: string) {
    this.greeting = message;
  }
  public greet(): string {
    let formatString = getFormat(this, "greeting");
    return formatString.replace("%s", this.greeting);
  }
}

The @decorator tag would be a block tag, whose content is simply the decorator signature as a code block.

Is this a good solution? What do you think?

[giniedp]

Awesome, having that information is a great value. Ofc. further parsing is needed wherever that information has to be evaluated. Also it is not possible to know where the decorator originally came from (renamed import). At least in my use cases both is not a problem.

[octogonz]

Should multiple decorators be represented using multiple @decorator tags?

How should it be displayed in the API docs?

Here's an example input:

/**
 * Used to change the sign of a number.
 * @remarks
 * For a positive number, the result is negative. For a negative number, the result is positive.
 * @param x - the input number
 * @returns the negated value
 * @decorator `@format("Hello, %s")`
 * @decorator `@sealed`
 */
@sealed
@format("Hello, %s")
function negate(x: number): number;

Idea A

Should the decorator strings get inserted above the signature, like below?

---

negate() function

Used to change the sign of a number.

Signature:

@format("Hello, %s")
@sealed
function negate(x: number): number;

Parameters

Parameter	Type	Description
x	number	the input number

Returns: the negated value

Remarks

For a positive number, the result is negative. For a negative number, the result is positive.

---

Idea B

Or should the decorator strings get presented separately, maybe like below?

---

negate() function

Used to change the sign of a number.

Signature:

function negate(x: number): number;

Decorators: @format("Hello, %s") @sealed

Parameters

Parameter	Type	Description
x	number	the input number

Returns: the negated value

Remarks

For a positive number, the result is negative. For a negative number, the result is positive.

---

[giniedp]

i'd vote for B, they should have a dedicated section in my opinion.

[octogonz]

Here's a PR: https://github.com/microsoft/tsdoc/pull/272