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 On 31/08/10 12:33, Vincent Hennebert wrote: > 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, <[email protected]> wrote: >>> >>>> Author: vhennebert >>>> Date: Fri Aug 27 13:31:41 2010 >>>> New Revision: 990148 >>>> >>>> URL: http://svn.apache.org/viewvc?rev=990148&view=rev >>>> Log: >>>> Replaced @asf.todo with normal TODO comment >>>> >>>> >>
