Mailing-List: contact dev-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Commons Developers List" <dev@commons.apache.org>
Received-SPF: pass (athena.apache.org: domain of phil.steitz@gmail.com
 designates 209.85.213.43 as permitted sender)
Message-ID: <4E2D8A3D.6060704@gmail.com>
Date: Mon, 25 Jul 2011 08:22:37 -0700
From: Phil Steitz <phil.steitz@gmail.com>
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6;
 rv:5.0) Gecko/20110624 Thunderbird/5.0
MIME-Version: 1.0
To: Commons Developers List <dev@commons.apache.org>
Subject: Re: [math] Inherits doc and @Override
References: <1311315486.2827.2.camel@knuffelchen>
 <20110724221359.GI7045@dusk.harfang.homelinux.org>
 <4E2C9BAB.6000508@gmail.com> <j0j0br$q63$1@dough.gmane.org>
 <4E2D0D85.2020606@gmail.com>
 <CAEQx=x=cVy2jm1xGYfP_YwoaFmrt-2VyHZsNKcXt6=F75tqYkA@mail.gmail.com>
 <CAOGo0Va-U+FJTHFxSB_F5vm=WS2xiHo5GiVCtKDBYKjfxWzyNQ@mail.gmail.com>
 <CAEQx=x=iM+YF+PK-vmKJ2W4Ouu7H1L+3SmfzXm49Y+G=Rdib4w@mail.gmail.com>
 <CAE9L6G1cjiG4z-aO-RjrEBMZcNaeY+RxLvBXT5W_TWyKCd-ruQ@mail.gmail.com>
In-Reply-To: 
 <CAE9L6G1cjiG4z-aO-RjrEBMZcNaeY+RxLvBXT5W_TWyKCd-ruQ@mail.gmail.com>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

On 7/25/11 6:31 AM, Matt Benson wrote:
> On Mon, Jul 25, 2011 at 5:07 AM, Torsten Curdt <tcurdt@vafer.org> wrote:
>>>> Good code needs little javadocs.
>>> I disagree strongly.
>>>
>>> The Javadoc should present the public API (and should ideally be
>>> written before the code - i.e. the code implements the docs).
>>>
>>> If the only documentation is the code, it is much harder for users to
>>> determine how to use the API.
> I have to agree.  Ever programmed against cglib?  When depending on
> libraries with no javadoc, I invariably find myself going to the code,
> which I really shouldn't have to do.  Of course, I must admit that
> even for libraries that appear to be reasonably well-documented (e.g.
> Spring), I still often end up going to the code.
>
>>> For some code (interfaces, abstract methods) only Javadoc is available.
>> Did you even bother to read the blog post?
> I read it, Torsten.  What I get from its main theme though is that you
> are encouraging the class-level "book" comment one sees in e.g.
> oac.jxpath.JXPathContext or Mockito's main Mockito class.  I suppose
> that's a matter of preference, but personally I prefer to digest an
> API in smaller bits than that.

Honestly, I think its best to have both.  Good class-level javadoc
describes the overall function of the class, primary properties and
use cases and macro-level considerations about what the class
expects from or how it interacts with its execution environment. 
Method level javadoc specifies contracts.   If you have to skimp on
one of these, for library code it is in general better to focus on
the method-level documentation, because that is what the user always
sees and depends on and also what can be validated by the unit tests.

Phil
>
> Matt
>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org