Description Dave Wichers 2008-10-25 10:29:09 EDT

Build ID: M20080911-1700

Steps To Reproduce:
Using the Javadoc warnings feature in Eclipse I'm running into two situations where I'm getting warnings that I don't think are appropriate.

#1) Use of @see tag with (non-Javadoc)

We are using this pattern:

    /* (non-Javadoc)
     * @see org.owasp.esapi.LogFactory#getLogger(java.lang.String)
     */
    public Logger getLogger(String moduleName) {

To pull in the javadoc from the interface that this method is implementing. Javadoc itself supports this just fine, but the javadoc warning tool in Eclipse warns that we are missing the Javadocs for this method.

We could declare the javadoc like this:

    /**
     * @see org.owasp.esapi.LogFactory#getLogger(java.lang.String)
     */
    public Logger getLogger(String moduleName) {

And the warning would go away, but the generated Javadoc is different and we prefer what is generated using the 1st pattern.

#2) Style for documenting parameter descriptions:

We use this pattern because it easier to read (we think):

    /**
     * Log a fatal event if 'fatal' level logging is enabled.
     * 
     * @param type
     *              the type of event
     * @param message
     *              the message to log
     */
void fatal(EventType type, String message);

The javadoc warning tool in Eclipse warns that we haven't provided the description for each of these parameters, but we have, they are just on the line after. Again, javadoc itself builds the javadoc just fine like this and we would prefer not to have conform to the expected style just to get the Javadoc warning to go away.

More information:
In conclusion: Is there a way to get this fixed? I think these would be very easy fixes. Since the generated javadoc works fine for both, seems like the warning tool should recognize them as valid too.