이희승 (Trustin Lee) skrev:
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.
Thanks,
IMO, omitting the Javadoc comment is better for overriden methods if
there is nothing additional to say. I don't care about the 'Description
copied from class: SuperType' message and even just having to type
@inheritDoc wastes my precious time :-) (ok, we could use a code
template for that I guess). I agree with Trustin that @inheritDoc is
useful only when you want to add something to the overridden method's
comment. Also, I would strongly suggest that we don't use
/**
* @see ...
*/
as those kinds of comments only mess things up in the final Javadoc
HTML. They also get in your way if you use a modern IDE (e.g. when
hovering over a method call I want to see the real javadoc, not just
"See also...").
/Niklas
