maven-doxia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Vincent Siveton" <vincent.sive...@gmail.com>
Subject Re: svn commit: r426203 - in /maven/doxia/trunk/doxia-sandbox/doxia-book: ./ src/main/java/org/apache/maven/doxia/book/services/indexer/ src/main/java/org/apache/maven/doxia/book/services/renderer/ src/main/java/org/apache/maven/doxia/book/services/r
Date Sat, 29 Jul 2006 01:48:09 GMT
[snip]

> >> These comments are pretty useless, I'd rather not sprinkle the code with
> >> obvious comments.
> >
> > Agree but if no comment, nobody thinks to had comment, specially for
> > new and important updates. my2cents ;)
>
> Not sure what you mean, please explain again.

We know that writing good and informative comments is hard and bad
comments are just a waste... My point is that a class without a
minimum of comments is likely to remain like this in the future:
nobody thinks or "dares" to add new comments.
For instance, the Sink interface and its implementations dont have a
lot of useful documentation even if several developers worked on it.
WDYT?

> > IMHO I think that Doxia needs to be review at large to add comment.
>
> Agreed, we need to document the important parts.

yep

[snip]

> >> > +    //
> >> > +    //    public void tableCaption()
> >> > +    //    {
> >> > +    //        type = TYPE_TABLE;
> >> > +    //    }
> >>
> >> Any special reason for this other than you identing it by accident?
> >
> > Well, it is not an accident: it is the Eclipse formatter with the
> > Maven Code Style
> > (http://maven.apache.org/guides/development/guide-m2-development.html)
> > Promise, I will try idea ASAP ;)
>
> That has never been a standard that I can recall. Comment blocks always
> start on column 1.

I know that it is not a standard! It is an Eclipse issue ;)
https://bugs.eclipse.org/bugs/show_bug.cgi?id=34552

[snip]

> >> I like these, they are separators between logical parts of the method.
> >
> > It is not a Maven standard style thus I removed it. Is it for Doxia?
> > If yes, we need a developping guide.
>
> They are very much a standard part of the Maven code, we (at least I)
> use it all the time.

I will do

Thanks,

Vincent

> > [snip]
> >
> >> > +
> >> > +    //
> >> -----------------------------------------------------------------------
> >> >      // Private
> >> >      //
> >> -----------------------------------------------------------------------
> >> >
> >> > +    /**
> >> > +     * Render the book, ie the book index and all chapter index
> >> > +     *
> >> > +     * @param book
> >> > +     * @param context
> >> > +     * @throws BookDoxiaException if any
> >> > +     */
> >> >      private void renderBook( BookModel book, BookContext context )
> >> >          throws BookDoxiaException
> >> >      {
> >> > -        //
> >> -----------------------------------------------------------------------
> >> > -        // Render the book index.xml page
> >> > -        //
> >> -----------------------------------------------------------------------
> >> > -
> >> >          File index = new File( context.getOutputDirectory(),
> >> "index.xml" );
> >> >
> >> >          try
> >> > @@ -86,12 +137,6 @@
> >> >          }
> >> >
> >> >          //
> >> -----------------------------------------------------------------------
> >> > -        // Render the index.html files for each chapter
> >> > -        //
> >> -----------------------------------------------------------------------
> >> > -
> >> > -        // TODO: Implement
> >> > -
> >> > -        //
> >> -----------------------------------------------------------------------
> >> >          // Render all the chapters
> >> >          //
> >> -----------------------------------------------------------------------
> >>
> >> Ditto here about the commends. They explain the flow in the code.
> >
> > IMHO javadoc should provide it ;) developing guide...?
>
> No, javadoc is not the same thing as inline comment. This is documenting
> the _code itself_ not what the class/method is supposed to do.
>
> [snip]
>
> --
> Trygve
>
>

Mime
View raw message