google / google/jsinterop-generator
Annotate elements with annotation or @since tag
- Dominant language
- Java
- Stars
- 85
- Forks
- 24
- PR merge metrics
- No merged PRs in 30d
Description
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](https://github.com/Fyrd/caniuse) 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.
Contributor guide
Assessment
This issue has not been assessed yet.