[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
