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.com>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, <vhenneb...@apache.org> 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 > >>> > >>> > > >