So, the conclusion is that:
* We shall not use @see-tags for overriding and implementing methods but
[EMAIL PROTECTED]
* Unless the actual implementation is explained in the javadoc.
I will formulate this in the Cookbook and change the Eclipse Code
Template default.
/Linus
> -----Original Message-----
> From: Tom Morris [mailto:[EMAIL PROTECTED]
> Sent: den 19 juli 2006 22:17
> To: [email protected]
> Subject: [argouml-dev] Checkstyle and @see javadoc for overriden
methods
>
> 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]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
