Dear Fop-devs, as always, I have no say in this, but what I usually do is to use
/** [EMAIL PROTECTED] */ This works really well, if the method inherits from a class / interface which is also present in the same codebase: Checkstyle is happy, and so is JavaDoc. Also, JavaDoc gives a warning if a method uses inheritDoc, but does not implement / override a method (a way of detecting renames in superclasses) For some more discussion on this matter, see [1] [1] http://mail-archives.apache.org/mod_mbox/jackrabbit-dev/200503.mbox/[EMAIL PROTECTED] hth Max Vincent Hennebert schrieb: > Hi, > > Nothing related with (and against) the original change, but I take this > one as an opportunity to launch the discussion. I've been having this in > my head for a while. > >> - /** @see org.apache.fop.layoutmgr.LayoutManager#initialize() */ >> + /** @see org.apache.fop.layoutmgr.LayoutManager#initialize() */ > > I'd like to suggest to remove such comments every time there's an > opportunity. They are useless for javadoc which is able to retrieve the > comment from the redefined method. They are painful when discovering > code in Eclipse because when we hover a method call, we get that comment > instead of the real one, which Eclipse also is able to retrieve. > > The only reason I can think of for such a comment is to make checkstyle > happy. But I don't think this is a solution. Checkstyle should be aware > that in Java redefined methods inherit their javadoc from the original > one, and shouldn't complain in this case. So here it's checkstyle that > is wrong. > > Anyway, there are already zillions of checkstyle warnings in the current > codebase, so I guess we can live with a few more. > > > WDYT? > Vincent
signature.asc
Description: OpenPGP digital signature
