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:


  1. On the element with the warning, open the actions menu (Alt+Enter by default)
  2. 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:

fun info(msg: String) { /* ... */ }

fun info(msg: String) { /* ... */ }


View Github