When a doc comment is written, the first argument to @param should match one of
the method parameters. In 1.4.2, if it does not match in spelling and case,
then @param is not printed. This causes important parts of the spec to
disappear when a user upgrades to 1.4. This is a mistake, and is contrary to
how javadoc worked prior to 1.4.
Instead @param should be printed with the misspelled argument, as in most cases,
the user can correlate the misspelled @param argument to the correct method
parameter, and benefit from reading the @param description.
For example, in constructor BeansContextServicesSupport:
/**
* ...
* @param dtime The initial state, true if in design mode, false if runtime.
* ...
*/
public BeanContextServicesSupport(BeanContextServices peer, Locale lcle, boolean dTime, boolean visible) {
super(peer, lcle, dTime, visible);
}
The first argument "dtime" is not capitalized properly, so neither it nor
its description is printed. It should be printed as-is.
Here is the parameter printout:
Parameters:
peer - The peer BeanContext we are supplying an implementation for,
if null the this object is its own peer
lcle - The current Locale for this BeanContext.
visible - The initial visibility.
This is the current warning for the above error:
/java/pubs/ws/mantis/make/docs/../../src/share/classes/java/beans/beancontext/BeanContextServicesSupport.java:59: warning - @param argument "dtime" is not a parameter name.