이희승 (Trustin Lee) wrote:
On Fri, 23 May 2008 14:21:07 +0900, 이희승 (Trustin Lee)
<[EMAIL PROTECTED]> wrote:
On Fri, 23 May 2008 13:59:46 +0900, 이희승 (Trustin Lee)
<[EMAIL PROTECTED]> wrote:
On Fri, 23 May 2008 13:52:49 +0900, Mike Heath <[EMAIL PROTECTED]>
wrote:
Emmanuel Lecharny wrote:
이희승 (Trustin Lee) wrote:
Every public methods except for the constructors are overridden
from its supertypes and interfaces. They all got proper JavaDoc
comments. Let me know if I am missing something.
Adding a @see Class#method() in the implementation then should
help. When you look at a method javadoc it's better to know where
too look at : the intheritance scheme can be feilry complex, and
it can be a burden to retreive the associated Javadoc.
Something like :
/**
* @see javax.naming.Context#close()
*/
public void close() throws NamingException
...
I think @see is the wrong approach for this situation. We should
use @inheritedDoc instead of @see. With @see you get no useful
information if your IDE supports in-editor popup docs. You also
have to make an extra click to get to useful information when
browsing the JavaDocs which is almost as annoying as empty docs.
Also with @inheritedDoc you can see immediately in the code that
there are JavaDocs for the method.
IMO using @inheritedDoc instead of empty JavaDocs should be the
standard practice in any Java project.
[EMAIL PROTECTED] is a good idea. However, it's only useful when you
have something to add to the supertype's documentation. Otherwise,
empty JavaDoc is simply replaced with the supertype's documentation
AFAIK. Therefore something like the following doesn't have much
meaning:
/**
* [EMAIL PROTECTED]
*/
Please let me know if I misunderstood how javadoc works.
I added [EMAIL PROTECTED] tags to some methods and found that
[EMAIL PROTECTED] removes 'Description copied from class: SuperType'
message when javadoc is generated. Other than that, I couldn't find
any difference. However, I don't like to see that annoying message
with close-to-zero information (i.e. copied from...), so I started to
like to add [EMAIL PROTECTED] to all empty JavaDocs.
BTW, I found that DefaultByteBufferQueue.size(), iterator() and
peek() have empty documentation in the generated JavaDoc. It's
probably because their documentation is in JDK rather than in local
source code. Do you know if there is any option that asks javadoc to
fetch JDK documentation?
Google got the answer:
http://forum.java.sun.com/thread.jspa?threadID=5264128&tstart=0
Interesting. Good to know.
-Mike
