google / google/jsinterop-generator

Annotate elements with annotation or @since tag

Open
#29 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.