Bernd Fondermann wrote:
Julien Vermillard wrote:
Hi,
The followed rule for MINA Javadoc is :
- a comment in each class header
- doco on each public/protected method (or on the parent class public
method with inherited tags)
The main point is to help user to understand the public API,
for the internal doco it's more flexible and it's good to hear great
feedback from Michael :)
Let's step back a little bit for a second for some general observations.
<snip/>
So, back on topic.
I don't think every single setter/getter method in Vysper needs javadoc.
They are typically generated automatically by any decent IDE, it's a no
brainer.
Frankly, I've got better things to do with my time than add redundancies.
Often, I sit before a class and think about what I should write into the
header javadoc. But nothing good comes to my mind other than repeating
what is already in the class name. I keep going on with something else.
<digression>
Sometime I feel the way you are, when I'm wondering which kind of header
I can add to explain what does a very basic Class like StringUtils, or a
very basic method like hexDump( byte[] value ), but at the end of the
day, it does not harm to drop a single line of comment... Also I'm
generally so deep into my code that I don't see that someone coming from
the outside may need some direction.
At the end of the day, it's also something I consider as painful as
re-reading a letter I wrote to check if I didn't misspelled a word, and
every time I do that, I discover some missing info, some better method
name, or even some bug I introduced.
It may be just me, but I feel that Javadoc is as useful as unit-tests.
Yeah, I know : no fun...
</digression>
But you are certainly right on the fact that Javadoc is more important
for MINA, as it's more important for commons-XXX than anything else.
In Vysper's commit log history you will notice one or more doc'athons
where a lot of doc is added. I will keep doing that. It's fun.
I don't think that only one way leads to Rome :)
--
--
cordialement, regards,
Emmanuel Lécharny
www.iktek.com
directory.apache.org
