In a lot of cases it would be desirable to document when an API became available. It would be great if this somehow made it through to generated java code. JsDoc has a @since tag that is roughly equivalent to javadocs @since tag. This is primitive but may work and we would need to figure out a way to represent versions either as a combination of @since spec-version or @since browser-version or some combo.
We could use this but as this is not present in closure compilers externs we may need to either add it to the externs (which seems unlikely to be accepted upstream) or use some sort of mechanism to walk the AST and add @since based on some rules (i.e. everything in w3c_dom1.js has @since dom.1. However even this may be too laborious and/or error prone.
A better approach may be to actually define a java annotation that can be used to annotated each method/field to indicate which browsers support method and what version ranges. i.e.
@SupportedBy({ @Browser(name = "Chrome", version="66", removed="74"), @Browser(name = "Firefox", version="47"), ... }). This could be built from the canisue database. This seems to be the "best" alternative but it is unclear how easy it would be to align the names of symbols.
The annotation based approach would also allow people to write annotation processors that verified that they were not using APIs they did not intend to.
In a lot of cases it would be desirable to document when an API became available. It would be great if this somehow made it through to generated java code. JsDoc has a
@sincetag that is roughly equivalent to javadocs@sincetag. This is primitive but may work and we would need to figure out a way to represent versions either as a combination of@since spec-versionor@since browser-versionor some combo.We could use this but as this is not present in closure compilers externs we may need to either add it to the externs (which seems unlikely to be accepted upstream) or use some sort of mechanism to walk the AST and add
@sincebased on some rules (i.e. everything inw3c_dom1.jshas@since dom.1. However even this may be too laborious and/or error prone.A better approach may be to actually define a java annotation that can be used to annotated each method/field to indicate which browsers support method and what version ranges. i.e.
@SupportedBy({ @Browser(name = "Chrome", version="66", removed="74"), @Browser(name = "Firefox", version="47"), ... }). This could be built from the canisue database. This seems to be the "best" alternative but it is unclear how easy it would be to align the names of symbols.The annotation based approach would also allow people to write annotation processors that verified that they were not using APIs they did not intend to.