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
> >>>
> >>>
> >
>

Reply via email to