Community
Participate
Working Groups
There are a number of settings I'd love to set for the javadoc checks in the compiler settings section, primarily: require all methods (regardless of visibility) to have javadocs allow multiple @throws per thrown exception But the current UI doesn't allow for that kind of detail. Are there any plans for making the Javadoc checks more configurable? If not, I'd like to request more configuration options :-)
JDT/Core provides the "real" function.
Why would you need multiple @throws per thrown exception ? Is it to be able to add each scenario behind ?
I'm not sure I understand your second question, but as to why multiple @throws per Exception, one example (the pattern I use most frequently) it to have one @throws for type checks and one @throws for range checks (when a failure in either will throw, for example, IllegalArgumentException)...
Marco, I don't understand your second requirement. May you provide a example? My assumption is that you want to have this kind of Javadoc: /** * @throws MyException between these range for this value * @throws MyException if this parameter has this type * @throws MyException ... * @throws MySecondException */ At my point of view you can write the same using current model: /** * @throws MyException * 1) between these range for this value * 2) if this parameter has this type * 3) ... * @throws MySecondException */ The model for Javadoc comment assumes that all lines following a line including a tag declaration owns to this tag until the next tag declaration (or the end of the comment of course). Otherwise, OK for your first suggestion which can be a possible additional option for Javadoc checking...
Well, I'm not married to the exceptions thing, and your solution works just as well. :-) Thanks for the methods -- please extend to also include fields?
Of course, this would be extended for methods, constructors, fields and types
Should we consider packages? Or should I enter another enhancement request for that?
If package means that user can set the visibility level from which the javadoc checks will be performed, then we can use this bug. First possibility would be that user had a radio button with four values: public, protected, package and private. Then, compiler would check only on methods, fields and types which would have a visibility equal or larger than the selected one. Second possibility would be that user has a multi-selection choice with the same four values. Then compiler would check methods, fields and types which would have been selected.
Actually, I was thinking along the lines of package-level javadocs... ie/ package.html. But, of your two ideas, IMHO, the second one adds unwarranted flexibility... (Again, this is merely my opinion, but I can't see the value of selecting "enforce javadocs for package-visible members, but not public members"...
Current option 'Missing Javadoc tags' will be changed to let user enter level of visibility he wants to report this problem instead of having just the choice to enable/disable it. Fix for this bug is ready but we need to synchronize with JDT-UI for release. See also bug 46976.
Martin, The existing compiler option COMPILER_PB_MISSING_JAVADOC will be changed as follow: * COMPILER / Reporting Missing Javadoc Comment * Specify the level of visibility from which the compiler will signal cases where class, interface, method, * constructor or field has no javadoc comment. When set to "never" value, the compiler will never complain * about missing javadoc comment. * The severity of the problem is controlled with option "org.eclipse.jdt.core.compiler.problem.invalidJavadoc". * - option id: "org.eclipse.jdt.core.compiler.problem.missingJavadoc" * - possible values: { "never", "public", "protected", "default", "private" } * - default: "never" As we need to be synchronized to release this change, I'll send you a JDT-Core jar file in order to have this bug and bug 46976 fixes and prepare corresponding change in JDT-UI to be able to display the new compiler options. I assign the bug to you to follow the work about this. When you'll be ready, then please reassign the bug to me and we'll release together at this time... Thanks
Marco, We'll add several options to make compiler error report on javadoc easier to control for user. For packages enhancement, please open a new bug, thanks
New options have been added for Javadoc problems. Complete definition of these new options is done in JDT-Core release notes: http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout% 7E/org.eclipse.jdt.core/buildnotes_jdt-core.html. Invalid references, missing tags (bug 47940) or missing comments (this bug and bug 47319) problems can be now ignored below a specific visibility level. Finally, user will also have the possibility to ignore missing tags and missing comments on overriding methods, assuming that complete Javadoc comments is done in superclass or interface declaration (see bug 46976).
Complete test cases created for this bug and related ones: jdt.core.tests.compiler.regression.JavadocTestOptions
Tests of new Javadoc Preference page was also done using HEAD from jdt-ui. All JDT-UI regression tests pass.
Verified for 3.0M6
