maven-doxia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Trygve Laugstøl <tryg...@apache.org>
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 Mon, 31 Jul 2006 09:53:13 GMT
Vincent Siveton wrote:
> [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?

You can't compare the Sink interface which is one of the most important 
interfaces in the entire Doxia product against obvious comments saying 
the exact same thing as the method name.

I do agree that we need to improve our javadoc, but I do not think that 
adding obvious comments is the way to go. I'd rather just take some time 
and document the parts which are not ovious.

>> > 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

Will you put back the comments that was removed?

--
Trygve

Mime
View raw message