Hi Mark, I disagree on two counts: 1. The code does have documentation because it inherits it, and this inherited documentation is viewable with widely available, widely used, free tools. 2. Anything is not necessarily better than nothing. You can turn on automatic comment generation in eclipse, but I would argue that this is definitely worse than nothing - you end up with javadoc, but it doesn't tell you anything that can't be implied from the code.
Having said that, I think what you were getting at (apologies for taking liberties!) is that not everything can have perfect documentation but that there should be some. And with this I agree, and think there are some places which give greater bang for buck as far as usefulness of the documentation goes, and some where the returns dwindle. Cheers, Brad. Mark Webb wrote: > As I try and follow this thread, I think we have lost the point to the > original issue which is that code is being checked in with no > javadocs. Sure, getting the proper javadoc tags is ideal, but > anything is better than nothing. > > > On Fri, May 23, 2008 at 4:45 AM, Brad Harvey <[EMAIL PROTECTED]> wrote: > >> Hi All, >> >> I'll add my opinion as a MINA user rather than developer. It's very >> important to make sure the javadoc for the public API is correct and >> complete. In this case that's the ByteBufferQueue interface. For the >> implementation class it's useful to have class level javadoc describing its >> characteristics and/or why I might use it rather than some other >> implementation (like the Collections javadocs), but a blow by blow on each >> public method really isn't necessary. Either its already covered by >> interface docs, or I'm probably not going to see them method entirely >> because I'm programming to the interface anyway. >> >> MINA maintainers probably want comments about implementation details in the >> implementation classes, but these are generally not javadoc comments on >> public methods anyway. >> >> Also remember the tools (IDE & javadoc) are only getting better with time. >> With primitive / non specialised tools you'll probably have more >> difficulties to deal with than not having @see tags. >> >> Cheers, >> Brad. >> >> Stefano Bagnara wrote: >> >>> Emmanuel Lecharny ha scritto: >>> >>>> 이희승 (Trustin Lee) wrote: >>>> >>>>> On Fri, 23 May 2008 12:21:43 +0900, Emmanuel Lecharny >>>>> >>>>>> Sometime, you just have to use vi or emacs. Make it simple for users : >>>>>> add a @see tag. Cost almost nothing, and it helps. >>>>>> >>>>> I wouldn't bother with vi or emacs. They pay for what they use. >>>>> Moreover, it's not 'almost nothing'. >>>>> >>>> -1. >>>> >>>> Please revert the commit. >>>> >>>> Thanks. >>>> >>> Emmanuel, are you vetoing the commit because an inherited class (having >>> full javadocs for the superclass) does not have method comments? >>> >>> Isn't this a bit hard at this point of the discussion? >>> >>> FWIW (I'm not committer to mina, but only a developer) I agree with >>> Trustin. >>> >>> If a @see is useful then the javadoc tools should automatically add the >>> see to every implementation method having no javadoc. This is about javadoc >>> tools, not documentation. The documentation is already in the java source >>> keywords "extends" and "implements". >>> >>> Stefano >>> >>> >>>
