RFC: "@decorator" tag for documenting ECMAScript decorators

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?

No implementation files or tests are named. Start by reviewing the proposal and its discussion, focusing on whether a stable @decorator block tag should be specified and how decorator signatures should be represented. Done would be a decided direction for accepting, revising, or rejecting the proposal.