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....
geir
Regards,
Tim
