How to document @SuppressWarnings("unused")?

Question

I extracted a module from a monolithic java project. The module contains public constants, which are used only outside of that module, but all over the application. Now I need to ignore the unused warnings via @SuppressWarnings("unused"), because there are a lot of constants and if I don't ignore those, they hide other warnings.

I actually dislike this approach, but semantically those constants belong to the module and at the very least I want to document why I chose to suppress the warnings in the first place. The javadoc page does not provide any hint on how to do this.

I am thankful for any advice?

Answer 1

As J.Bloch sugested in Effective Java (probably Item 27, Eliminate unchecked warnings), I just add simple non-javadoc comment on the line with this annotation, which explains why it is ok to suppress warnings there.

It doesn't seem to me, that it is interesting to user of your API what warnings are suppressed, so I wouldn't worry about javadoc and for developer actually reading the code the comment is enough.

So in your case I'd probably go like:

//Many of the constants are unused, but removing them would require figuring out their values
//and names some day
@SuppressWarnings("unused")  
public class Foo {