You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ant.apache.org by Jesse Glick <je...@sun.com> on 2006/11/15 21:46:20 UTC
Re: svn commit: r475078 - /ant/core/trunk/src/main/org/apache/tools/ant/types/optional/depend/DependScanner.java
peterreilly@apache.org wrote:
> inheritDoc
>
> URL: http://svn.apache.org/viewvc/ant/core/trunk/src/main/org/apache/tools/ant/types/optional/depend/DependScanner.java?view=diff&rev=475078&r1=475077&r2=475078
> ==============================================================================
> - /**
> - * @see DirectoryScanner#getIncludedFilesCount
> - */
> + /** {@inheritDoc}. */
> public synchronized int getIncludedFilesCount() {
Note that you can simply delete the Javadoc comment altogether:
/** {@inheritDoc} */
is equivalent to no comment at all, and is appropriate when an override
of a method adds no notable semantics beyond what is already specified
in the superclass' Javadoc. Also you probably did not want the trailing
'.' in there.
> /**
> * @see DirectoryScanner#getExcludedDirectories
> */
> + /** {@inheritDoc}. */
(and elsewhere)
Did you really mean to leave two comments in place?
-J.
--
jesse.glick@sun.com x22801 netbeans.org ant.apache.org
http://google.com/search?q=e%5E%28pi*i%29%2B1
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: svn commit: r475078 - /ant/core/trunk/src/main/org/apache/tools/ant/types/optional/depend/DependScanner.java
Posted by Jesse Glick <je...@sun.com>.
Peter Reilly wrote:
>> Note that you can simply delete the Javadoc comment altogether:
>
> Yes, I know, but 1) checkstyle does not
So shouldn't you patch checkstyle? :-)
> 2) javadoc will check that there is doc to inherit when one puts in inheritDoc.
But checkstyle would already be warning you about any lack of superclass
Javadoc anyway, right? (Unless you have a method in a public class
overriding a method in an inaccessible class. Which IMHO is evil.)
> Having comments for get/set is especially tedious.
Yes, it is. Don't think there's anything to be done about it, other than
avoiding the beans pattern in APIs to begin with.
> Do not know about the trailling dot......
/** {@inheritDoc}. */
vs.
/** {@inheritDoc} */
> Yes, as the original coder when to the trouble to document
> the place that this was inherited from for readers of the code.
I see. Probably a job for IDEs in general, though.
> The point of the exercise is to make the checkstyle
> of ant to be a usefull activity
Which is a good step.
-J.
--
jesse.glick@sun.com x22801 netbeans.org ant.apache.org
http://google.com/search?q=e%5E%28pi*i%29%2B1
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: svn commit: r475078 -
/ant/core/trunk/src/main/org/apache/tools/ant/types/optional/depend/DependScanner.java
Posted by Antoine Levy-Lambert <an...@gmx.de>.
Hello Peter,
this is a lot of work, but I also think that it is useful.
Regards,
Antoine
-------- Original-Nachricht --------
Datum: Wed, 15 Nov 2006 21:33:36 +0000
Von: "Peter Reilly" <pe...@gmail.com>
An: "Ant Developers List" <de...@ant.apache.org>
Betreff: Re: svn commit: r475078 - /ant/core/trunk/src/main/org/apache/tools/ant/types/optional/depend/DependScanner.java
> The point of the exercise is to make the checkstyle
> of ant to be a usefull activity, at the start of the exercise
> there was > 5000 reported violations of coding practices,
> this makes it impossible to use to find violations when
> adding/modifing code and some dodgy code had crept in.
> (no javadoc, and horrors brackets in the wrong place, and
> a few evil tabs).
>
> Peter
>
> >
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: svn commit: r475078 - /ant/core/trunk/src/main/org/apache/tools/ant/types/optional/depend/DependScanner.java
Posted by Peter Reilly <pe...@gmail.com>.
On 11/15/06, Jesse Glick <je...@sun.com> wrote:
> peterreilly@apache.org wrote:
> > inheritDoc
> >
> > URL: http://svn.apache.org/viewvc/ant/core/trunk/src/main/org/apache/tools/ant/types/optional/depend/DependScanner.java?view=diff&rev=475078&r1=475077&r2=475078
> > ==============================================================================
> > - /**
> > - * @see DirectoryScanner#getIncludedFilesCount
> > - */
> > + /** {@inheritDoc}. */
> > public synchronized int getIncludedFilesCount() {
>
> Note that you can simply delete the Javadoc comment altogether:
>
> /** {@inheritDoc} */
Yes, I know, but 1) checkstyle does not and 2) javadoc will
check that there is doc to inherit when one puts in inheritDoc.
>
> is equivalent to no comment at all, and is appropriate when an override
> of a method adds no notable semantics
> beyond what is already specified
> in the superclass' Javadoc.
I tried in some (well a very very few) cases to capture this, but
it can be difficult when the original coder did not put any comment
in. Some (a lot) of the inheritDocs could be replaced by a does
nothing comment (for methods of interfaces) but it can be tedious
to document each field (otherwise checkstyle will whine).
Having comments for get/set is especially tedious.
{
/** verbose attribute, if true ... */
(@Property boolean verbose;
} would be nice....
> Also you probably did not want the trailing
> '.' in there.
Do not know about the trailling dot......
>
> > /**
> > * @see DirectoryScanner#getExcludedDirectories
> > */
> > + /** {@inheritDoc}. */
>
> (and elsewhere)
>
> Did you really mean to leave two comments in place?
Yes, as the original coder when to the trouble to document
the place that this was inherited from for readers of the code.
The point of the exercise is to make the checkstyle
of ant to be a usefull activity, at the start of the exercise
there was > 5000 reported violations of coding practices,
this makes it impossible to use to find violations when
adding/modifing code and some dodgy code had crept in.
(no javadoc, and horrors brackets in the wrong place, and
a few evil tabs).
Peter
>
> -J.
>
> --
> jesse.glick@sun.com x22801 netbeans.org ant.apache.org
> http://google.com/search?q=e%5E%28pi*i%29%2B1
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
> For additional commands, e-mail: dev-help@ant.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org