On 7/24/11 10:52 PM, Jörg Schaible wrote:
> Hi Phil,
>
> Phil Steitz wrote:
>
>> On 7/24/11 3:13 PM, Gilles Sadowski wrote:
>>> Hello.
>>>
>>>> I saw in the sources serveral /** {@inheritDoc} */ on methods with
>>>> @Override annotation. Javadoc knows to inherit the javadoc of the
>>>> overwritten methos, so there is no need for @inheritDoc.
>>>> If all agree, one could drop this if the code is modified?
>>> CheckStyle complains if there isn't a Javadoc block.
> Bad argument. Adjust the rule.
>
>> Right, and including it creates a placeholder to expand on or modify
>> the inherited javadoc. I think we should keep it.
> We finally removed it in our code base here at my company and it looks so
> much cleaner. Why keep superfluous lines of "boiler plate stuff" without any
> relevance? If there is something to document on, I'd expect a little more
> than {@inheritDoc} anyway.
Here's the problem as I see it. Code with no javadoc is bad, bad,
bad. Especially for library code, which is what we do here.
Removing the check opens the door to this badness. Maybe a "bad
argument" but practical (unless there is some simple checkstyle
magic that I don't know about, which is quite possible). Secondly,
every time I paste in {@inheritDoc} or see it in our code, I ask
myself if the inherited doc is accurate and adequate. I know you
may respond that the same could apply just looking at the @Override
and emptiness, but I personally like seeing the javadoc block
there. I won't complain about removal if we can find a way to keep
the check functioning without adding ad hoc work for committers; but
I don't personally see this as a problem.
Phil
>
> - Jörg
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> For additional commands, e-mail: dev-h...@commons.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
