This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.
Recent builds display a light bulb and an annotation on the right hand for every class member that doesn't have javadoc. I think this is in many cases too obtrusive. I am working on a project with a lot of undocumented members in almost each class; it's impossible and not even desirable to fix all of them. My problem with this new feature is that the bulbs/annotations clutter all the vertical margins space, which prohibits me from clearly seeing really important stuff - current line marker, breakpoint and error annotations, light bulbs for error and import fixes. Please provide a way to turn javadoc warnings off and make them disabled by default.
As a quick fix you can disable the javadoc module. Since there are missing editor hints options it is impossible to customize them now. I have expected similar complaints so I limited javadoc hints just for public&protected members of public&protected classes/interfaces/... until options will be available. Making javadoc hints disabled by default would be false IMO. It would be hard to discover them for most users. BTW a lot of javadoc warnings may show a wrong design -> you have everything public. In case you ignore using javadocs it seems to be appropriate to disable the javadoc module at all as I mentioned above. Honzo, what is the target milestone to introduce editor hints options? IMO they should allow to select what should be notified and how it should be notified (warning, error, ...).
Yes, this is a real-world project, which means it is not perfect. Still, turning javadoc off isn't an option, because, as it happens, newer code, in particular the code I write myself, is better documented, and that's where IDE javadoc features should come in handy. Re: default value - the way our code looks right now with all the new lightbulbs and annotations is annoying, and many of my colleagues, who are used to Eclipse, would be seriously bothered by this, if they ever took a look at NB. Now, while I agree that changing the default will indeed make the feature less discoverable, I believe that it's preferable to having a feature that outright annoys a large part of target audience.
Hmm, hard to help. You say bulbs are annoying but later that they are handy :-) What comes to my mind is to limit hints count per type. Options would look as a table of Hint Type, Enable/Disable, Severity, Max count. For now I could implement it to read a system property.
Unless you are implying that "javadoc features" and "javadoc lightbulb features" are equivalents, or that the javadoc module only provides lightbulbs, I suggest you to re-read my last comment, paying a closer attention to relations between words. Re hint counts and temporary property: thumbs up.
I have added several options to limit number of hints. For now they are implemented as system properties: 1. max number of Create Missing Javadoc hints, default is Integer.MAX_VALUE org.netbeans.modules.javadoc.hints.MissingJavadocLimit=[int] 2. max number of Add/Remove Javadoc Tag hints, default is Integer.MAX_VALUE org.netbeans.modules.javadoc.hints.FixJavadocTagLimit=[int] 3. see http://java.sun.com/javase/6/docs/technotes/tools/solaris/javadoc.html#javadocoptions for description, default is 'protected' org.netbeans.modules.javadoc.hints.Visibility=[public|protected|package|private] You may use whatever combination of these properties. Use -J-D to prefix properties on the command line or in {nb.install.dir}/etc/netbeans.conf In case a limit of hints is overrun then together with the last hint a warning occurs, informing that remaining source code was not analyzed. Implemented in /cvs/javadoc/src/org/netbeans/modules/javadoc/hints/Bundle.properties new revision: 1.2; previous revision: 1.1 /cvs/javadoc/src/org/netbeans/modules/javadoc/hints/JavadocHintProvider.java new revision: 1.4; previous revision: 1.3
Great job, thanks!
"In case a limit of hints is overrun then together with the last hint a warning occurs, informing that remaining source code was not analyzed." This sounds like a reasonable compromise... so why not enable a limit by default? Very few users are going to know to set some system property, and even if there is an option in the Options dialog somewhere I doubt many people would see it. If the first few methods in a class have no Javadoc, and I have not fixed them yet, it is unlikely that I want to see warnings about other methods. (Unless I disagree with the IDE about the need for Javadoc comments on the first few methods, but actually want other methods documented. But this is probably a corner case.) More generally, there should probably be a consistent system for dealing with editor hints. If I see a warning with a hint, I would like to see options (in the following order): 1. Fix the problem (multiple items if there are multiple possible fixes). 2. Suppress the warning in this one case, e.g. with an annotation or a special comment, if that makes sense. 3. Turn off all warnings of this type in this project. Best to make the choice per-project, since different projects may have quite different code styles. (Can keep a list of disabled warnings in AuxiliaryConfiguration, shared or private.) For #3 you would also need some GUI to reenable selected warnings. Or just quietly reenable a warning after a week has passed since it was disabled! Sounds weird, but it might work out. Disabling a warning only takes a couple seconds so if it is only necessary once a week it would not really be annoying. Yet you would not be in danger of permanently forgetting that a class of useful warnings exists just because you needed to concentrate on other things one day.
Yes, Jesse's suggestions seem reasonable. I can imagine there's an item in the hint popup menu to disable this warning or all warnings of the same class. That should help discoverability. In addition to that, there should be an options panel in the options dialog controlling the warning/hint behavior. BTW, how do you show the warning about reaching the limit number of warnings? I agree it would be good to turn the limit on by default and tell the user with the warning message how to change the limit when the limit is reached.
I would like to remind that options as system properties are only a temporary solution for users of daily and milestone builds. The goal is to have ui options. But it should be solved for all editor hints not just javadoc ones. Unfortunately I have found just issue #89598 that does not explain a lot. jlahoda should know about hints options more. Re limits by default What default limit do you expect as reasonable? Lower limits might not be always comfortable. If you add some new code at the bottom of an existing source your code will not be most likely analyzed. So IMO fix tags hints should be unlimited warnings and missing doc hints could be limited (20?) not warnings, but hints by default. IMO it would be also useful to allow to change severity (annotation icon+editor stripe color) of hints. E.g. someone may consider broken javadoc as an error, for me it is rather a warning and others want this to be just a hint. BTW other possible options rather for code generator could be: * prefer @throws or @exception * how to wrap with asterisks * indentation I'll attach a screenshot of the last hint warning.
Created attachment 38510 [details] screenshot of warning