harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tim Ellison <t.p.elli...@gmail.com>
Subject Re: Writing JavaDoc
Date Mon, 16 Jan 2006 11:28:07 GMT
Geir Magnusson Jr wrote:
> 
> Tim Ellison wrote:
> 
>> Loenko, Mikhail Y wrote:
<snip>
>> I agree it is good practice to document the implementation of some
>> non-API code for developers.
> 
> Some? why not all?

... because by definition the non-API code does not require
documentation for the user.  Where the implementation is simple and
'obvious' to the developer it seems pointless to write reams of doc too.

>>  That documentation may or may not be
>> JavaDoc.  For example, many people typically don't do a full JavaDoc
>> comment for a private method.
> 
> Where would you put it?

In a non-Javadoc comment.

<snip>

>> AFAIK other projects that are implementing JSRs etc write the code and
>> documentation to go alongside it rather than link to the reference.
> 
> 
> How do you go "alongside"?

(erm, I must be missing your question here)

...by putting the Javadoc comment in the same .java file as the
implementation, instead of putting a link in the .java file to a website

Regards,
Tim

-- 

Tim Ellison (t.p.ellison@gmail.com)
IBM Java technology centre, UK.

Mime
View raw message