microsoft
RFC: @version tag
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.
Should it be an inline tag? For example: {@version 1.1}
Should we allow multiple instances of this tag?
Looks like JSDoc already has something similar, although the web site docs don't give much detail about its intended usage.
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.
@beta is a modifier tag that cannot have any content. @remarks is a block tag that starts an entire document section containing rich text.
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.
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}?).
@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.
@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?
@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 {
}
@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.
@remarksor@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.2would 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.
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.
@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?
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.
@sharwell Thanks for sharing that jQuery link. It makes an argument for an introduced and depreciated tag (I'm guessing in a d.ts file, you'd just remove the API in question when it's gone and leave it up to the reference documentation to track when it was removed).
I prefer the @since syntax a little more over the @version syntax. The version syntax just reminded how apiDoc handles versions. Inside the generated doc you can toggle yourself through the version history of the endpoint which might be a niche case for TS methods but in some cases for changed parameters it could be neat to cycle through the versions(if documented).
JQuery seems to track three version:
- Version when the API was added
- Version when it started being deprecated
- Version when it was finally removed
It seems like the removed version cannot be represented in TSDoc (unless a placeholder is left in the file somehow). I wonder if they must use some other system to track this, since they still show complete signatures and documentation for the removed API. I know that DocFX is able to track documentation for different releases of a library.
This feature seems like it could be valuable. However if we want it to be standardized (versus implemented using custom tags), then someone needs to propose a more complete design that shows how the tags are used together.
For the first version of TSDoc, can't we leave out the added/deprecated/removed use-case and just stick to @since or @version ?
To me, it feels like adding support for indicating when a method was deprecated or removed is another use case, which might warrant their own tags (and which can be added later), e.g.
@since 1.0
@deprecated 3.5
@removed 5.0
Both @version and @since are used in our enterprise project and I would love to have support for them. And for @removed and @depreacted they both are the same for me and as of jsdoc only @deprecated is documented (idk but "removed" tells me it should have been removed from the code at all).
We use it like this:
/**
* This is an example.
*
* @param hey - describe
*
* @since 2.4.1
* @version 1.0.1
*/
@since- indicates when it was added and refers to the application version@version- is special and not often used but mostly tells us which version this function/class has so it can be used in issues later
order is not important but they are always at the end
Just want to chime in that I also think @since would be a slick addition.
