I gave up on the whole coding conventions discussion a while back, but this issue raised by Michiel never got resolved. I think it's important because it reduces the usefulness of Checkstyle and it's not going away. Contrary to what he says below, upgrading Checkclipse/Checkstyle isn't going to fix the problem. This is a permanent change to Checkstyle and the only thing that got "fixed" in Checkstyle 4.1 was that the documentation was updated to match the implementation. The @see tag by itself for an overriding method still triggers a warning.
We need to either turn off this check in Checkstyle or fix our Javadoc. Since the current Javadoc style with the @see reference doesn't provide any useful information in Eclipse 3.2 (this might be a change from 3.1), I'd prefer to see the Javadoc fixed. Either way, we need to change something. Tom > -----Original Message----- > From: Michiel van der Wulp [mailto:[EMAIL PROTECTED] > Sent: Thursday, May 25, 2006 3:28 PM > To: [email protected] > Subject: Re: [argouml-dev] Coding conventions > > > Hi Linus, > > This is my conclusion: We must have a different Checkstyle version! > > I have Checkclipse V1.7.0 with Checkstyle 4.0. > You must have a version before V4.0. > > > The change history of Checkstyle: > > > Release 4.1 > Documentation for JavadocMethod check corrected to indicate > that after > fix for 1290379 javadoc which contains only @see tag is not valid any > more (bug 1369615) > > Release 4.0 > Now javadoc method should not contain only @see tag (but > could contain > only [EMAIL PROTECTED] tag) (bug 1290379, module JavadocMethod) > > Release 3.3 > Fixed handling of inheritDoc in JavadocMethod check (bug 855839). > > > So, we better wait until V4.1 of Checkstyle comes with a new > Checkclipse... in the meanwhile, I commented out the > JavadocMethod check > in the configuration. > > For more info, see bug 1369615 at: > http://sourceforge.net/tracker/index.php?func=detail&aid=13696 > 15&group_id=29721&atid=397078 > > > > Short version of this story - for in the cookbook? - please confirm!: > > > > If you have version V4.0 of Checkstyle, and it gives lots of warnings > that JavaDoc is missing for such a case: > /** > * @see org.tigris.gef.presentation.FigGroup#addFig() > */ > public void addFig() { ... > > then you have to comment out this part: > > <!-- module name="JavadocMethod"> > <property name="scope" value="protected"/> > <property name="allowUndeclaredRTE" value="true"/> > </module --> > > in the file argouml-core-tools.checkstyle.checkstyle_argouml.xml > > > Regards, > Michiel > > > > > Linus Tolke wrote: > > Hello Michiel! > > > > Earlier I have, by experimenting, found that putting the > @see first in > > the javadoc comments, the warning about the argument disappears. In > > your example, that would mean removing the text before the > @see solves > > the problem. I cannot reproduce it now. This is strange. > > > > Eclipse supports this because we have the default comment > created for > > inherited methods to: > > /** > > * ${see_to_overwridden} > > */ > > I see now that the new Eclipse setup and especially the > > eclipse-argo-codetemplates.xml does not include this like it was > > explained in the Cookbook > > > (http://argouml-downloads.tigris.org/nonav/argouml-0.20/cookbook-0.20. > > pd > > f 9.7.2). I will fix that. > > > > I don't understand how > > * @see inherited class#inheritedmethod(argument) > > and > > * [EMAIL PROTECTED] > > differ. They guess they mean very much the same thing. I have > > preferred the first alternative because it works so well > with Eclipse > > and checkstyle. > > > > When reading the classes that implement several interfaces in the > > editor, it is occasionally useful to have it stated what interface > > this method belongs to. That would be in favor of the first > > alternative. > > > > When changing methods it is extra work to update the javadoc. That > > would be in favor of the second alternative. > > > > When you test the two alternatives in Eclipse/checkstyle, do the > > [EMAIL PROTECTED] behave better than the @see x.y.z? > > > > /Linus > > > >> -----Original Message----- > >> From: Michiel van der Wulp [mailto:[EMAIL PROTECTED] > >> Sent: den 25 maj 2006 12:17 > >> To: [email protected] > >> Subject: Re: [argouml-dev] Coding conventions > >> > >> Hi Linus, > >> > >> MVW: > >>> Currently, it always gives a few warnings for every function with > >>> parameters, and I do not find any way to suppress these > warnings. So > >>> I try not to look at them, and switched off checkstyle warnings, > >>> since they drown in the useless ones... > >> Linus: > >>> It is unlucky that you are feeling that Eclipse warns too much. I > > don't > >>> understand from your description, where your warnings come from. > >> > >> Digging into the problem I found out that CheckStyle _IS_ the > >> problem. I get warnings for every method like this one: > >> /** > >> * Called after the notation default property gets changed. > >> * > >> * @see > >> > > > java.beans.PropertyChangeListener#propertyChange(java.beans.PropertyCh > > an > > ge > >> Event) > >> */ > >> public void propertyChange(PropertyChangeEvent pce) { > >> .... > >> > >> And, after reading > >> http://checkstyle.sourceforge.net/config_javadoc.html#JavadocMethod > >> I found out that I can suppress the warnings by: > >> > >> /** > >> * Called after the notation default property gets changed. > >> * > >> * [EMAIL PROTECTED] > >> */ > >> public void propertyChange(PropertyChangeEvent pce) { > >> .... > >> > >> ...or by commenting out the > >> <module name="JavadocMethod"> > >> > >> <property name="scope" value="protected"/> > >> > >> <property name="allowUndeclaredRTE" value="true"/> > >> > >> </module> > >> > >> in the checkstyle_argouml.xml file - which is not desired. > >> > >> I like the [EMAIL PROTECTED] solution for esthetical reasons, but it is > > quite > >> some work to go adapt everywhere... > >> > >> What shall we do? > >> > >> Regards, > >> Michiel > >> --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
