I agree. TODO should be something for the developer of the objects. Javadoc should be something for the developer of something which implements those objects. They don't really belong together. I'd keep separate documentation if you want to let the implementing programmer know what the developing programmer is planning to do next. I think taking the @ off the TODO makes sense.
-----Original Message----- From: Jeremias Maerki [mailto:d...@jeremias-maerki.ch] Sent: Wednesday, September 08, 2010 8:19 AM To: fop-dev@xmlgraphics.apache.org Subject: Re: TODO tag [was: Re: svn commit: r990148 - in /xmlgraphics/fop/trunk/src/java/org/apache/fop: area/ fo/ fo/flow/ fo/flow/table/ fo/pagination/ fo/properties/ hyphenation/ layoutmgr/ layoutmgr/inline/ layoutmgr/table/] +1! On 08.09.2010 13:02:29 Vincent Hennebert wrote: > Ok, let me summarise this: > > * a @[asf.]todo tag marginally improves the formatting of a javadoc > comment > * nobody really likes the idea of using a namespaced version of todo > (@asf.todo) > * it is possible to tweak Checkstyle and the javadoc command to enable > the use of @todo > > That said: > * todo statements generally have little to do (sic) in a javadoc comment > anyway > * TODO keywords are easily indexable by modern IDEs > > Jeremias recommends the Felix way: using //TODO comments below the > javadoc. I'm also strongly in favour of this convention. OTOH, if I'm > correct nobody strongly feels that @todo tags are necessary. > > So I think we have a consensus: > * from now on we stop using @todo in favour of the Felix convention; * > we will progressively remove TODO statements from javadoc comments and > move them below in their own Java // comments * I remove the > definition of the custom tag from build.xml > > Let me know if I missed anything. > > Thanks, > Vincent <snip/> Jeremias Maerki
