Community
Participate
Working Groups
3.2 Not sure whether this is possible at all, but consider this fragment: public class X { /** * API method, see also {@link #bar()}. */ public void foo() {} /** * Private comment. */ void bar() {} } Depending on the javadoc settings used, the reference to the method bar() from the comment of foo() will be invalid since bar() will not be included in the documentation. If the user chooses to include package private members in the javadoc, everything is perfectly valid, however.
See also bug 110964
Even if you generate only at public level, javadoc does not raise any warning on this test case. The link in foo javadoc comment is well created, the only thing is that you cannot access it as it was not generated... Invisible only means for references inside code and we already have a specific option for that.
The current implementation replicates Javadoc's bug (see also bug 53977), but this wrongly leads people to think their Javadoc is clean while in fact, it still contains dangling references. See e.g. in attachment 79464 [details] of bug 201426: Javadoc of SearchPattern#validateMatchRule(String, int) refers to private and undocumented #validateCamelCasePattern(String).
(In reply to comment #3) > The current implementation replicates Javadoc's bug (see also bug 53977), but > this wrongly leads people to think their Javadoc is clean while in fact, it > still contains dangling references. > > See e.g. in attachment 79464 [details] of bug 201426: Javadoc of > SearchPattern#validateMatchRule(String, int) refers to private and undocumented > #validateCamelCasePattern(String). > This is not true. No warning is reported on this reference because Javadoc compiler preference is set to 'Private' visibility on org.eclipse.jdt.core project. If you change the Javadoc compiler level to 'Default' or higher, then you'll get the expected warning "Javadoc: 'default' visibility for malformed doc comments hides this 'private' reference"
You're right, flagging that reference to a private member of the enclosing type only makes sense if private members are not going to be included in the generated Javadoc. To find such problems, I guess we would need a second setting besides the current 'Only consider members as visible as' option, e.g. 'Report references with lower visibility than' [Public|Protected|Package|Private]. This new option could then be used as the default in the Javadoc export wizard. Low priority, though.
