Description Frederic Fusier 2008-11-18 07:01:47 EST

When a javadoc comment is misplaced in the code, it will be ignored by the javadoc tool while generating the documentation.

It could be interesting to warn users that there's a potential issue on this kind of comments. Of course, this warning would be controlled by a new Javadoc compiler preferences and would be disabled by default...

Bug 252555 and bug 254825 exhibit this behavior, but here's a typical test case merging all cases I have in mind:

/**
 * Package javadoc comment is ignored by the javadoc tool except for the 
 * specific package-info.java file...
 * 
 * Our compiler always parses it but intentionally does not report any warning
 * if the compilation unit is not package-info.java.
 */
package my.pack.age;

/**
 * Duplicate javadoc comments are ignored both by the javadoc tool and by our
 * compiler.
 */
/**
 * Only the last javadoc comments is used while generating the documentation
 * or parsed by our compiler.
 */
public class Test {

    class X {
        /**
         * Javadoc comments in member types are not ignored by javadoc tool.
         * 
         * It's parsed and resolved as well by our compiler.
         */
        void foo() {}
    }
    Object foo(Object o) {
        class Y {
            /**
             * Local types are ignored by javadoc tool, hence javadoc comments
             * defined there are not included in the generated doc.
             * 
             * However, our compiler parsed and resolved these javadoc
             * comments.
             */
            void foo() {}
        }
        /**
         * Statements are ignored by javadoc tool, hence javadoc comments
         * defined there are not included in the generated doc.
         * 
         * There are neither parsed nor resolved by our compiler.
         */
        return new Object() {
            /**
             * Anonymous classes are ignored by javadoc tool, hence javadoc 
             * comments defined there are not included in the generated doc.
             * 
             * However, our compiler parsed and resolved these javadoc
             * comments.
             */
            void x() {}
        };
    }
}