As suggested by @mmczaplinski in Documentation 2.0 Structure maybe we could start doing adding a @since
tag in our TSDocs for reference of when a feature/API was added.
WordPress does it with the @since tag. For example:
/**
* Checks if a block can be read.
*
* @since 5.0.0
*
* @param WP_Post $post Post object that backs the block.
* @return bool Whether the block can be read.
*/
In our case, it is not going to be that simple, because we don’t know the exact version that is going to be next, depending on the type of bump (minor or patch).
One idea would be to populate it with a NEXT
tag, for example, and run a script that replaces all the NEXT
tags with the bumped version of each package before the release.
We commit this:
/**
* Do something.
*
* @since NEXT
*/
And a script does a commit before the release, once the package.json
files have been updated to replace all the @since NEXT
found with the package.json
versions:
/**
* Do something.
*
* @since 1.13.1
*/
Maybe to not overengineer it we could use an @after
tag and add the current version.
For example, this means that this API is not available in version 1.13.1
or below. It is not as nice, but the final information is the same.
/**
* Do something.
*
* @after 1.13.1
*/
Any other ideas?