Community
Participate
Working Groups
In Preferences/Java/Compiler/Javadoc, I have set "Malformed Javadoc comments" to true. When I insert a {@link ClassName#methodName()} in the javadoc of one of my classes, and "methodName()" is protected, it triggers the warning: Javadoc: the method methodName() from the type ClassName is not visible Which is true, but there again, creating a javadoc reference to a protected method in another class is not like calling it; I feel it's probably a fairly legitimate thing to do most of the time and also causes no complaints from javadoc when it is run (generating javadoc against public and protected members which is fairly normal too). Is it possible to add an option to disable the warning for this case while keeping warnings for other types of malformed comments? My specific example if your interested is below. The protected method in question is Visitor.traverse(ParentClass). /** * Calls {@link Visitor#visit(ThisClass)}. Note that {@link Visitor} can be * subclassed to provide custom traversals. If the traversal of a {@link ParentClass} * is customized, the overridden method {@link Visitor#traverse(ParentClass)} * would call this method only if it wants to traverse <code>ThisClass</code>. * * @param visitor the {@link Visitor}. */ public void accept(Visitor visitor) { visitor.visit(this); }
This is a requirement for a new option, not a bug.
*** Bug 60571 has been marked as a duplicate of this bug. ***
Post 3.0
I think this is a bug, not a feature request. The fact that a reference is non-visible in code does not apply for Javadoc references. To fix it, I don't think adding a new option is the way to go, simply do not report that warning. I would suggest to have that in 3.0 as otherwise I can't get my code warning- free what lowers the usability of the Javadoc compiler warnings.
I disagree. We treat Javadoc exactly as we treat source code. Visibility is enforced, and I suspect the extra warnings you can't get rid of are not in real API javadoc. If so, these would likely be inconsistent since targeting entities which aren't part of the javadoc in the end. This is a useful warning. We may tweak it some more post 3.0.
Try my example in bug 60571. Generate documentation using javadoc.exe and you get (with no warning or error) the documentation containing a link to a method that I couldn't call in my code due to visibility restrictions, but that Javadoc obviously still allows my to refer to in my documentation. The Javadoc tool is setting the rules here, we shouldn't invent our own. Note that there might be somthing related: We can say to only generate documentation for public members. In that case it would make sense to warn on all references that point to protected or less visible members. This is not the problem here. Here I configured to document all classes. Maybe that's what you had in mind, but then the current implementation has a bug.
*** Bug 75068 has been marked as a duplicate of this bug. ***
Reconsider for 3.1
Fixed. New compiler option has been added to address this issue: * COMPILER / Reporting Invalid Javadoc Tags with Not Visible References * Specify whether the compiler will report non-visible references used in Javadoc tags. * <br>Note that this diagnosis can be enabled based on the visibility of the construct associated with the Javadoc; * also see the setting "org.eclipse.jdt.core.compiler.problem.invalidJavadocTagsVisibility". * - option id: "org.eclipse.jdt.core.compiler.problem.invalidJavadocTagsNotVisibleRef" * - possible values: { "enabled", "disabled" } * - default: "enabled" * See also bug 75701. [jdt-core-internal] Test cases added in JavadocTestOptions.
Verified for 3.1M3 with build I20041102
*** Bug 84683 has been marked as a duplicate of this bug. ***
