RFC: @version tag

[AlexJerabek]

Customer often need to know the versions of particular classes, methods, and properties so they can target specific releases. While this information can be passed through the description, it would be beneficial for downstream tooling to avoid parsing extra text.

My request would be to let this field be an arbitrary string. So @version 1.1 and @version Excel API 1.4 both work.

[octogonz]

Should it be an inline tag? For example: {@version 1.1}

Should we allow multiple instances of this tag?

[octogonz]

Looks like JSDoc already has something similar, although the web site docs don't give much detail about its intended usage.

[AlexJerabek]

I would think @version would be the same level of importance as @beta and @remarks. It's important information for an evergreen d.ts file.

[octogonz]

@beta is a modifier tag that cannot have any content. @remarks is a block tag that starts an entire document section containing rich text.

[AlexJerabek]

I can't think of a scenario where you'd need a multi-line version. I'll trust your judgement on the tag category.

Multiple version tags would be interesting, but probably too complicated to get the desired behavior. The scenario for needing multiple versions is documenting a change, like a property that's read-only in v1 and not in v2. But getting a tag to connote that information would be excessive. You're better off just tagging the property v1 and explaining the behavior change in the remarks.

tl;dr: Probably best to have one instance per class/interface/property/function.

[octogonz]

An inline tag seems like a better design, since it clearly conveys that we want a small text string that shouldn't contain any markup:

/**
 * The Widget class.
 * {@version 1.2}
 */
export class Widget {
}

The syntax and meaning of the 1.2 version string would be implementation-defined.

However, if JSDoc's @version block tag is already widely used and has the exact same semantics, then maybe we should follow their syntax:

/**
 * The Widget class.
 * @version 1.2
 */
export class Widget {
}

/**
 * This also works, since it's a block tag
 * @version 
 * 1.2
 */
export class Widget2 {
}

/**
 * The Widget class.
 *
 * @version 1.2
 *
 * Don't put text here!  It will (confusingly) be considered to be part of the block.
 */
export class Widget3 {
}

This seems error-prone, however. We could work around it by adding nonstandard parsing rules for @version, however I'm hoping to minimize grammar irregularities because it makes it harder for people to learn the syntax.

Can anyone find more detail about how JSDoc's @version feature works?

@AlexJerabek if what you're proposing has some differences from JSDoc's feature, we could rename the tag to something else ({@apiVersion}? {@versionLabel}?).

[AlexJerabek]

@pgonzal Is it better to have the familiarity with @version, despite the block tag problems? Or is it okay to add a new, albeit less error-prone term?

My vote would be to copy the existing JSDoc standard and behavior. While the user could inadvertently add a block of text to their version, it would be easy to catch.

[Rick-Kirkham]

@pgonzal @AlexJerabek I'm not clear on the implications of the problem where a block of text is added. Does this mean that
@version 1.2
would have to be the last thing in any description? If so, is that a problem?

[AlexJerabek]

@Rick-Kirkham It could go anywhere after the initial description. You could have

/**
 * The Widget class.
 * @remarks
 * Details...
 * @version 1.2
 */
export class Widget3 {
}

or

/**
 * The Widget class.
 * @version 1.2
 * @remarks
 * Details...
 */
export class Widget3 {
}

You just can't have

/**
 * The Widget class.
 * @remarks
 * Details...
 * @version 1.2
 * More remarks...
 */
export class Widget3 {
}

[octogonz]

@Rick-Kirkham The basic idea here is that TSDoc is supposed to have a standard grammar for documentation tags. The 3 kinds of tags are:

• block tags (e.g. @remarks or @param) which start a new block -- everything after this tag is considered part of the block, until we encounter another block tag
• modifier tags (e.g. @public) which cannot capture any content, and do NOT create blocks
• inline tags (e.g. {@link Button | the button} whose content is captured between { and }. These tags do NOT create blocks. They become part of the currently active block.

Does this mean that
@version 1.2
would have to be the last thing in any description? If so, is that a problem?

It means that when people use @version, they "should" not put any content after 1.2 but before the next block tag. This is not obvious to authors. If they break the rule, it's unclear what we should do with that extra content.

The obvious way to handle this is to introduce special nonstandard grammar rules for handling the @version tag, based on the idea that we want to achieve compatibility with the JSDoc tool. The downside is that special nonstandard grammar rules are undesirable: They make it more difficult for people to learn the standard rules.

[sharwell]

I find @version to be a bit ambiguous. I would consider using @since instead, as it clarifies that this is the version where the API is introduced (or stabilized), and another tag could be used where applicable for the version where the API is deprecated.

[AlexJerabek]

@sharwell Hmm, I didn't consider the need to convey a range of versions. Would something like @addedInVersion be more descriptive? That's akin to how Android docs describe things in their doc set. I'm suggesting this to have the tag encapsulate the meaning.

We could also have @apiSet. I feel that implies a forward-inclusion, though that may be not globally intuitive. If something drops out, a separate tag (@deprecated?) could convey that information.

Of course, part of the benefit of using @version was to mirror JSDoc. Do you think clarity on meaning outweighs losing an easy mapping between the two systems?

[sharwell]

jQuery is the first place I saw multiple versions documented, and I found it fascinating enough to remember. I don't know if it's enough good to be a best practice, but here's an example showing all three versions (added, deprecated, removed):
https://api.jquery.com/jQuery.browser/

Do you think clarity on meaning outweighs losing an easy mapping between the two systems?

I don't use TS/JS enough to have any weight placed on my answer to this.