harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Geir Magnusson Jr <g...@pobox.com>
Subject Re: Writing JavaDoc
Date Mon, 16 Jan 2006 11:45:02 GMT

Tim Ellison wrote:
> 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.

But who is the "user" here?  Since we give all the code away, our 
"users" also happen to be other developers working with the library from 
the POV of implementation.

>>>  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.

Oh - sure - that works.  I was thinking that you might have meant 
somewhere else.

> <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

By "link" I mean to the official spec Javadoc.   I thought that's been 
the meaning of the notion of "linking to the spec" since the thread began.

Of course we put our javadocs in the .java file to which they belong. 
It would be insanity to do anything else....


> Regards,
> Tim

View raw message