API-Annotate
A single annotation for annotating externally-consumed elements in your libraries.
What? Why?
IDEs like IntelliJ helpfully flag up unused elements. But if you’re writing a library, often you’ll have lots of externally-facing functions and properties
that aren’t consumed inside the project at all. The IDE will give a false positive warning on these, which can lead to real unused functions getting ignored
and never cleared up.
If you annotate your externally-consumed elements with @API, you can instruct your IDE to suppress warnings on those annotated elements by
following these steps:
IntelliJ:
- On the element with the warning, open the actions menu (Alt+Enter by default)
- Select “suppress unused warning if annotated by com.sagehadnt.apiannotate.API”
Why not SuppressWarnings(“unused”)?
Because that doesn’t tell the reader why we’re suppressing those warnings. Having a dedicated annotation makes it unambiguous. The reader doesn’t
have to waste mental effort figuring out what the writer was trying to do.
Also, I’d argue it’s just cleaner:
@SuppressWarnings("unused")
fun info(msg: String) { /* ... */ }
@API
fun info(msg: String) { /* ... */ }
