Community
Participate
Working Groups
+++ This bug was initially created as a clone of Bug #53977 +++ Consider following settings: * Process Javadoc * Only consider members visible as: protected * Report non visible references With following code: class Foo { /** Doc of CONSTANT */ protected final static int CONSTANT = 1; /** Doc of CONST2 * @see #CONSTANT */ protected final static int CONST2 = 2; } This generates a warning at the "@see #CONSTANT" tag, because CONSTANT is located in class Foo which is only package-visible. I find this warning incorrect for two reasons: 1.) Javadoc is referencing a member from the same class, which does have protected visibility as requested. 2.) Javadoc being currently generated is only package-visible itself, so it should be ok to reference package-visible doc comments. In a real run of a Javadoc tool, the comment that's generating the warning would only be considered when that Javadoc tool enables doc-comments for package visibility. When this is done, the reference resolves correctly. I think that the following algorithm should be applied: * When processing doc comment of member X, * If warnings for doc-comment visibility are switched on: 1. Determine visibility of X itself as the "lowest" of all parent visibilities (would be "package" due to Foo in this example) 2. Set the "minimum allowed visibility" for doc-comment references as the minimum of current visibility and specified visibility from the Project/Preference settings (would override "Protected" with "package" in this example) The rationale of this request is that (3rd party) code might have been written with Doc-comments including comments for protected, package or even private members. But the project picking up and modifying this code might only be interested in documenting public members; thus the settings are changed for "public only" warnings. Any protected, package or private Javadoc is now in a "dormant" state. Therefore, correct references from this dormant state should not irritate current developers, and should not force them to switch off Javadoc reference visibility warnings at all.
Discussing this with Frederic, we agreed that the warning message is not as clear as it could / should be. This warning message intends to notify user that the current Javadoc settings (only consider protected members - Report non visible references) may hide the visibility of this member's parent. That is: user is trying to find non-visible reference problems in the Javadoc of protected members BUT the class's visibility is default. As an illustration of this problem, try and generate the Javadoc of the code used as sample, using the same settings as those set in Eclipse. Project --> Generate --> Javadoc and select "protected" members The result will be: nothing generated and the message: Loading source file D:\usr\OTI\wks\tests\v33\eclipse\testBug217891\src\Foo.java... Constructing Javadoc information... javadoc: error - No public or protected classes found to document. 1 error So, we agree the warning message could be improved to warn user of this possibly inaccurate settings.
Hm.. I think that I see your point, but the Javadoc settings can only be changed per-project and not per-file as far as I know? So if my project has lots of public / protected API that I do want to get checked; and one "default visible" class with some protected members plus APIDoc that I do NOT want to get checked; why do I have to live with the Warnings? If I had Java5, I could probably @annotate() to get rid of the warning, but I'm still on 1.4 so I think that Javadoc Warnings should be suppressed if the element in question would not be considered by a Javadoc tool with the same settings.
Perhaps the point is that the "Only consider members as visible: protected" setting is not properly honored, since a protected member inside a default-visible class should still NOT be considered. The default-visible container trumps the protected-visible member.
(In reply to comment #3) may the conjunction / usage of the term "visible" in both the 2 Javadoc preferences can be misleading: main pref: only consider members as visible as ... sub pref: report non visible... May be the main pref should read: "only consider members as" to point out that only <current_setting> members will be considered.
I can't see what it helps to change the description but keep the current behavior. A user who chose to only consider members which are "public" or "protected" for Javadoc verification indicates, that he intends to create API docs for these visibilities. Any containers with lower visibility will not be part of that Javadoc. Checking that Javadoc does not seem correct or intended behavior.
Ownership has changed for the javadoc comments bugs, but I surely will not have enough time to fix your bug during the 3.5 development process, hence set its priority to P5. Please provide a patch if you definitely need the bug to be fixed in this version and I'll have a look at it... TIA
+1 I am facing the same problem. Linking from one package protected (default visiblity) class to another causes such warning what is pointless.
