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
+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
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
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
Re: TODO tag
Of the three options: 1. @todo 2. @asf.todo 3. //TODO I prefer @todo, even if it means having a javadoc warning, but perhaps that warning can be suppressed. G. On Thu, Sep 9, 2010 at 1:24 AM, Simon Pepping spepp...@leverkruid.euwrote: //TODO is unstructured. @todo fits into an existing syntax, viz. that of javadoc tags. Output in javadocs can be suppressed by '-tag todo:X'. My preference is therefore a javadoc tag, @todo. But I am not going to make a case of this. +0. Simon On Wed, Sep 08, 2010 at 12:02:29PM +0100, 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. -- Simon Pepping home page: http://www.leverkruid.eu
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
On Thu, Sep 2, 2010 at 6:04 PM, Jeremias Maerki d...@jeremias-maerki.chwrote: I'm not sure we have the tooling to make sure noone uses @todo. Actually, checkstyle 5.1 will report warnings for any use of a non-standard tag that is not qualified with a dotted prefix. Also the standard Doclet in recent JDKs will complain as well. So if committers run checkstyle and javadocs targets before committing, we should be able to keep this usage out. On the other hand, it may be possible to fine tune the checkstyle rules and also the doclet options to permit use of @todo without warnings. I could try to experiment some to see if that is feasible, then we could return to the former usage of @todo. G.
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
On 02.09.2010 12:14, Glenn Adams wrote: also the doclet options to permit use of @todo without warnings. I could try to experiment some to see if that is feasible, then we could return to the former usage of @todo. Javadoc 1.5 or later can be passed a command line option defining additional tokens to accept: http://download.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#tag I vaguely remember to have had it working in my local build.xml some times ago. J.Pietschmann
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
Hi, I just thought I would homogenize our usage of todo tags and match what seems to be the de facto standard (“TODO”) among current committers. Most @todo indeed come from very old commits. I didn’t realise that javadoc could do something with them, which is why that looked to me like a minor change that wasn’t needing prior discussion. Sorry about that. Ok, so there is something that can be done out of @todo tags in javadoc comments. Now, having to use our own namespaced version is unfortunate and looks overkill to me. Just to have a slightly better formatted javadoc? Are such comments of any use to users of the API anyway? Most of them rather look like pure internal development issues and should probably not even appear in the javadoc. Also, while @todo tags can be indexed, modern IDEs can index plain TODO tokens as well, so that reduces the advantage of @asf.todo IMO. If there are strong feelings against the removal of @asf.todo, I’ll revert the change. Otherwise, I’ll actually complete it by removing the definition of the custom tag in build.xml, which I hadn’t spotted. Vincent Simon Pepping wrote: It would indeed have been better to first have a discussion and then make the change. @asf.todo is specific enough that we could have changed it at any time. That said, Glenn's change was also made without a discussion. My javadoc does not complain about the @todo tag, and I had not understood that this was a motivation. The javadoc documentation (of my sun-java6-jdk) is not clear about this topic, and uses @todo liberally in its section about the -tag option. Its most informative paragraph is this: Avoiding Conflicts - If you want to slice out your own namespace, you can use a dot-separated naming convention similar to that used for packages: com.mycompany.todo. Sun will continue to create standard tags whose names do not contain dots. Any tag you create will override the behavior of a tag by the same name defined by Sun. In other words, if you create a tag or taglet @todo, it will always have the same behavior you define, even if Sun later creates a standard tag of the same name. which does not even go so far as to discourage the @todo tag. It is also not clear how a todo tag would be a specific asf tag, different from the todo tag of any other organization. Everybody uses todo and means the same with it. Using the widely recognized TODO keyword circumvents the tag question altogether, but is outdated since the advent of tags. Let us discuss this and not waste effort on undoing each other's expression of their point of view. Let us also not forget that working in a team requires compromises; the code will never match your own conventions and preferences as precisely as code in your very own project. This is more so in an open project with a long history and a large set of authors. Simon On Sat, Aug 28, 2010 at 09:28:06AM +0800, Glenn Adams wrote: Vincent, Could you explain your rationale for this change? Originally, these were all marked with a non-standard '@todo' javadoc tag, which javadoc complained about, indicating that for non-standard tags, there should be at least one '.' present in the tag name. I had fixed this by adding the asf. prefix, which still allowed tracking these in javadoc more easily. However, your change now removes the utility of the tag. On a more general point, wouldn't it be more useful to have a discussion about stylistic changes prior to implementing them? Just so we can get on the same page? Regards, Glenn On Fri, Aug 27, 2010 at 9:31 PM, vhenneb...@apache.org wrote: Author: vhennebert Date: Fri Aug 27 13:31:41 2010 New Revision: 990148 URL: http://svn.apache.org/viewvc?rev=990148view=rev Log: Replaced @asf.todo with normal TODO comment
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
I don't have a strong opinion on whether to keep the @asf.todo or TODO. My main interest was removing the javadocs warnings produced (under jdk1.6 doclet) through the former use of @todo. My point in bringing it up was to request that we discuss beforehand prospective changes that back-out or reverse prior commits. G. On Tue, Aug 31, 2010 at 7:33 PM, Vincent Hennebert vhenneb...@gmail.comwrote: Hi, I just thought I would homogenize our usage of todo tags and match what seems to be the de facto standard (“TODO”) among current committers. Most @todo indeed come from very old commits. I didn’t realise that javadoc could do something with them, which is why that looked to me like a minor change that wasn’t needing prior discussion. Sorry about that. Ok, so there is something that can be done out of @todo tags in javadoc comments. Now, having to use our own namespaced version is unfortunate and looks overkill to me. Just to have a slightly better formatted javadoc? Are such comments of any use to users of the API anyway? Most of them rather look like pure internal development issues and should probably not even appear in the javadoc. Also, while @todo tags can be indexed, modern IDEs can index plain TODO tokens as well, so that reduces the advantage of @asf.todo IMO. If there are strong feelings against the removal of @asf.todo, I’ll revert the change. Otherwise, I’ll actually complete it by removing the definition of the custom tag in build.xml, which I hadn’t spotted. Vincent Simon Pepping wrote: It would indeed have been better to first have a discussion and then make the change. @asf.todo is specific enough that we could have changed it at any time. That said, Glenn's change was also made without a discussion. My javadoc does not complain about the @todo tag, and I had not understood that this was a motivation. The javadoc documentation (of my sun-java6-jdk) is not clear about this topic, and uses @todo liberally in its section about the -tag option. Its most informative paragraph is this: Avoiding Conflicts - If you want to slice out your own namespace, you can use a dot-separated naming convention similar to that used for packages: com.mycompany.todo. Sun will continue to create standard tags whose names do not contain dots. Any tag you create will override the behavior of a tag by the same name defined by Sun. In other words, if you create a tag or taglet @todo, it will always have the same behavior you define, even if Sun later creates a standard tag of the same name. which does not even go so far as to discourage the @todo tag. It is also not clear how a todo tag would be a specific asf tag, different from the todo tag of any other organization. Everybody uses todo and means the same with it. Using the widely recognized TODO keyword circumvents the tag question altogether, but is outdated since the advent of tags. Let us discuss this and not waste effort on undoing each other's expression of their point of view. Let us also not forget that working in a team requires compromises; the code will never match your own conventions and preferences as precisely as code in your very own project. This is more so in an open project with a long history and a large set of authors. Simon On Sat, Aug 28, 2010 at 09:28:06AM +0800, Glenn Adams wrote: Vincent, Could you explain your rationale for this change? Originally, these were all marked with a non-standard '@todo' javadoc tag, which javadoc complained about, indicating that for non-standard tags, there should be at least one '.' present in the tag name. I had fixed this by adding the asf. prefix, which still allowed tracking these in javadoc more easily. However, your change now removes the utility of the tag. On a more general point, wouldn't it be more useful to have a discussion about stylistic changes prior to implementing them? Just so we can get on the same page? Regards, Glenn On Fri, Aug 27, 2010 at 9:31 PM, vhenneb...@apache.org wrote: Author: vhennebert Date: Fri Aug 27 13:31:41 2010 New Revision: 990148 URL: http://svn.apache.org/viewvc?rev=990148view=rev Log: Replaced @asf.todo with normal TODO comment
