Emmanuel Lecharny ha scritto:
I withdraw my veto, as the missing @inheritDoc have been added to the file.
It would have been so much easier, and less noisy to simply do it
without arguing, the only discussion would have been about which tag to
use (I don't really like the @inheritdoc tag - and I may be wrong about
that -, but at least expose to the user that the javadoc is available in
an interface or upper class. We may discuss it beside this thread, and
inject the result of this discussion into the MINA code best practice).
Sure. If Trustin simply did what you asked with your veto we would have
a lot of @see or copy&paste comments and it would be a lot worse.
I personally think that @inheritdoc is clutter when you don't need to
add anything to the doc, but anyway this would have been much easier if
it didn't start with a veto ;-)
IMHO a similar scenario is better solved with the committers involvement
and not with a veto from a single PMC member. the community idea about
the style should be collected and then followed. There could be people
out there with deep knowledge of javadocs and why a given style is good
or bad and it is better to discuss new solutions instead of closing in
your opinions with an early veto.
In my environment the javadoc generation for a class with no javadocs
implementing an interface with javadocs simply generate this:
-----
Description copied from interface: #InterfaceName#
#InterfaceMethodJavadoc#
------
This also happen for extensions.
The [EMAIL PROTECTED] (at least in my environment) simply "hide" the fact
that the doc is identical to the superclass/interface doc so it reduce
the available informations.
Furthermore if you use [EMAIL PROTECTED] you don't have the link to the
superclass/interface that you would have with a @see and that is
automatically added if you don't have a javadoc at all.
That said, is your complaint about the generated javadoc or the code itself?
Stefano
