Formed in 2009, the Archive Team (not to be confused with the archive.org Archive-It Team) is a rogue archivist collective dedicated to saving copies of rapidly dying or deleted websites for the sake of history and digital heritage. The group is 100% composed of volunteers and interested parties, and has expanded into a large amount of related projects for saving online and digital history.
Join GitHub today
GitHub is home to over 50 million developers working together to host and review code, manage projects, and build software together.
Sign upGitHub is where the world builds software
Millions of developers and companies build, ship, and maintain their software on GitHub — the largest and most advanced development platform in the world.
RFC: "@decorator" tag for documenting ECMAScript decorators #271
Comments
|
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. |
|
Should multiple decorators be represented using multiple 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 AShould the decorator strings get inserted above the signature, like below?
Idea BOr should the decorator strings get presented separately, maybe like below?
|
|
i'd vote for B, they should have a dedicated section in my opinion. |
|
Here's a PR: #272 |
ECMAScript decorators use syntax like this:
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:
The
@decoratortag 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?