API Contract Tags

As I’ve review the TypeDoc and AEDoc supported tags, there emerged a special type of tag. These modifier tags override the TypeScript definition for external documentation purposes.

@readonly (supported by AEDoc) @private, @protected, and @public (supported by TypeDoc, AEDoc has a different @public)

Should this pattern be expanded or discouraged? In what cases does it make sense to have documentation deviate from implementation?

[petebacondarwin]

@pgonzal - sorry I’m a bit late to this party. @aciccarello is spot on. We use dgeni to do our documentation generation, which by itself does very little.

The bulk of the processing is in dgeni-packages which includes a jsdoc package and also typescript package. The former parses out jsdoc tags (which are completely configurable on a project by project basis) and the latter parses TS source code and infers lots of properties that would otherwise need jsdoc tags.

On top of that we have project specific configuration in the angular project at https://github.com/angular/angular/tree/master/aio/tools/transforms.

The list of tags linked to above is the “standard” ones that that the jsdoc package supports but for our purposes we add in a bunch of extra ones via https://github.com/angular/angular/tree/master/aio/tools/transforms/angular-api-package/tag-defs and https://github.com/angular/angular/tree/master/aio/tools/transforms/content-package/tag-defs. Some of which might be out of date and unused 😱.

As @aciccarello points out, this is not the whole story because we can then modify docs before they are rendered by processors, which is what is happening in the computeStability processor for the stability flags.

Happy to provide more detail of all of this if it is helpful to anyone.

[aciccarello]

Looks like they removed @stable

• angular/angular#22635
• angular/angular#23210

Here’s their list of tags https://github.com/angular/angular/tree/master/aio/tools/transforms/angular-api-package/tag-defs

Here is where the stable property is calculated https://github.com/angular/angular/blob/658f49f650dd90c784312845e63061d3268f5c84/aio/tools/transforms/angular-api-package/processors/computeStability.js#L7-L14