I tend to use @inheritDoc, rather than just omitting javadoc, to show that I'm intentionally reusing the existing documentation.
I prefer to also avoid manually copying existing documentation, since I think it's always best to try and avoid duplication where possible. In my opinion, duplication (of documentation, as well as code) is a big potential source of errors. Of course, I'm fairly new to collaborative open source programming, so perhaps there is less chance of error when you have lots of enthusiastic people reviewing commits. :-) Cheers Rich On Fri, May 23, 2008 at 5:21 PM, 이희승 (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? > > > Thanks, > -- > Trustin Lee - Principal Software Engineer, JBoss, Red Hat > -- > what we call human nature is actually human habit > -- > http://gleamynode.net/ >
