Usually, though, type parameters don't require explicit documentation since their meaning is obvious.
19.2.4. @return
The @return tag documents the return value of a method:
@return The number of words actually read.
19.2.5. @throws and @exception
The @tHRows tag documents an exception thrown by the method or constructor. If you use @tHRows tags
you should have one for each type of exception the method throws. This list often includes more than just the
checked exceptions that must be declared in the throws clauseit is a good idea to declare all exceptions in
the throws clause whether or not they are required, and the same is true when you're using @tHRows tags.
For example, suppose that your method checks its parameters to ensure that none is null, tHRowing
NullPointerException if it finds a null argument. You should declare NullPointerException
in your tHRows clause and your @tHRows tags.
@throws UnknownName The name is unknown.
@throws java.io.IOException
Reading the input stream failed; this exception
is passed through from the input stream.
@throws NullPointerException
The name is null.
The tag @exception is equivalent to @throws.
19.2.6. @deprecated
The @deprecated tag marks an identifier as being deprecated: unfit for continued use. Code using a
deprecated type, constructor, method, or field may generate a warning when compiled. You should ensure that
the deprecated entity continues working so that you don't break existing code that hasn't yet been updated.
Deprecation helps you encourage users of your code to update to the latest version but preserves the integrity
of existing code. Users can shift to newer mechanisms when they choose to instead of being forced to shift as
soon as you release a new version of your types. You should direct users to a replacement for deprecated
entities:
/**
- Do what the invoker intends. "Intention" is defined by
- an analysis of past behavior as described in ISO 4074-6.
- @deprecated You should use dwishm instead
- @see #dwishm
*/
@Deprecated
public void dwim() throws IntentUnknownException;
While the compiler may generate a warning if it sees the @deprecated tag, it is guaranteed to generate a