I would like some way to refer to method parameters while writing Javadoc comments.
Currently, I can have something like:
/**
* Print a message.
*
* @param message The message to print, defaults to <code>"hello world!"</code> if <code>null</code>.
* @param upperCase If <code>true</code>, <code>message</code> will be converted to {@link String#toUpperCase() upper case} before printing.
*/
public static final void printMessage(String message, boolean upperCase) {
String outMessage = (message != null) ? message : "hello world!";
if (upperCase) outMessage = outMessage.toUpperCase();
System.out.println(outMessage);
}
The problem is that in the section "@param upperCase If <code>true</code>, <code>message</code>", there is nothing to concretely identify "<code>message</code>" as a parameter, and link it to it's associated @param block description.
Also, currently, if I refactor my code by renaming the "message" method parameter in Eclipse, it will also automatically rename the Block level @param in the Javadoc, which is great, but fails to notice and similarly rename the <code>message</code> reference in the upperCase description text. This should be fixable with a solution to this.
An Inline version of @param could be created, like "{@param message the text}" which would work similarily to {@link}, creating a navigable HTML link to the @param block description for the message parameter, with "the text" as the text of the link (optional). This has the slight disadvantage of not being able to link to parameters for other methods. And perhaps overloading @param with different behavior when used as Inline vs Block isn't the best idea, though it could also be named something else ("{@paramlink}" ?).
Alternatively, the {@link} tag could be extended to allow referencing not just a method, but a parameter somehow. Something like "{@link #printMessage(String, boolean)@message the text}"?