ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Peter Reilly" <peter.kitt.rei...@gmail.com>
Subject Re: svn commit: r475078 - /ant/core/trunk/src/main/org/apache/tools/ant/types/optional/depend/DependScanner.java
Date Wed, 15 Nov 2006 21:33:36 GMT
On 11/15/06, Jesse Glick <jesse.glick@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


Mime
View raw message