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
