>>> 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>
Adding one more dimension to this. We can't assume that everyone shall use our *Code/Product* the same way. People might be interested in building things atop our Code/API's, by reusing or extending. Here is where the documentation helps a lot. Also, a *well* documented code attracts a large user community (that's an important thing for us) and possibly lot of committers as well :-) A very good example could be ApacheDS. You can actually take out lot of MINA codecs from there like for DNS, DHCP etc, and I am sure somebody might have used them without using complete code/product. > 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 :) > thanks ashish
