NullSafe JavaDoc Annotations (Optional)

There are many ways to "properly" deal with a NullPointerException. You can write code to prevent it, you can document the fact that you throw NullPointerException in JavaDoc, or you can document your API contract that your function doesn't support NULL parameters.

NullSafe supports all of these methods. API documentation can push the responsibility of non-null parameters back to method callers (see right). JavaDoc can also inform callers that you are supposed to throw under certain conditions. You can even annotate a single line source code to tell NullSafe to ignore that case.

Pushing responsibility to the caller

When a function's input parameter is not supposed to be null, you can annotate this fact by putting "@nonnull" anywhere in the JavaDoc for that parameter. This clearly documents this intent to callers. You can even format that tag specially in your JavaDoc output if you wish.

When this annotation exists, NullSafe will assume that parameter is non-null when analyzing your function. But other code that calls your method now inherits this constraint — now if someone else calls your method with an input value that could be null they get an error. In this sense you have "pushed" the responsibly for null-checking onto the caller of your method.

Your method return value can be similarly documented by putting "@nonnull" someone on the JavaDoc line with "@return". This adds a constraint to your implementation — now if you attempt to return something that could be null you'll get an error — but other code that calls your method can now depend on the fact that you don't return null; this will save the caller some headaches.

Throwing NullPointerException on purpose

Some API contracts require you to throw NullPointerException. Many of the core Sun Java objects are like this. In those cases, NullSafe will want to report an error but you know this to be erroneous.

There are two ways to fix this. First, you can declare NullPointerException in the "throws" section of your Java method declaration. This clearly shows the caller that you might throw that exception, so NullSafe will honor that too and not report that exception in your method.

The second way is to put a "@throws NullPointerException" section if your method's JavaDoc. This also shows the caller that you might throw that exception, so NullSafe will honor it.

Disabling null-detection from JavaDoc

Sometimes you want to disable the null-checking system for an entire class or an entire method. Often this is used when applying NullSafe to a legacy code base where it's not practical to start check all code right away.

You can use the "@npeUnchecked" tag anywhere in class or method JavaDoc to disable the system for that element. This way you're still running the NullSafe tool but you're documenting the fact that your code is, in fact, un-checked.

Disabling checking for a single line

Occassionally you want to disable the null-checking on just a single line of code. This might be to get around a false-positive that isn't obvious in static analysis.

You can do this by putting a "//"-style comment on that line containing the text "NONPE". This documents the fact that you're not checking that line, and if someday you want to eliminate these you can have your IDE list them out (using a facility similar to that for "TODO" and "FIXME") or even just use grep to find that string in your codebase.