A Todo filter

[Jason van Zyl <jv...@periapt.com>]

Hello,

Would anyone be interested in an ant task that
would pass through a set of source files and
create a project wide TODO list.

I am playing around with Velocity and there
are so many things to be done, but I'd like
a TODO document to be made from the source.

I was thinking something like:

/*!
 * @desc An Exception should be thrown here
 *       instead of triggering a NPE.
 * @priority 1
 */

All of these could be collected for a source
file and organized by package, sorted by
priority, location in the file (line #)
where the work needs to be done.

Is there already something like this?

It wouldn't take long to make something like
this, and I know I would really like it if
a TODO could be generated every night from
the sources and made publicly accessible.

I would probably make a small parser using
JavaCC.

Any thoughts?

jvz.

-- 

Jason van Zyl
jvanzyl@periapt.com

Re: A Todo filter

[Peter Donald <do...@mad.scientist.com>]

Just in case you want to know we used to do this at a place I used to be at
- we had specials tags for

FIXME
TODO
ERROR
HACK
FUDGE
etc

Each one was meant for things we had to go back and eventually change. We
embedded the authours initials at the end of the line so we could identify
who put it in there. The comments were rarely large because it was mostly
obvious from the context in which they were written.

So examples would be

//TODO: Need extra error checking here (PD)
//FIXME: Make sure variable Y is valid and has feature X (JC)
//HACK: Ugly hack needs to be removed once subsystem X is written (PR)
//FUDGE: Too lazy to do properly fix if it is accepted (MD)

We use to run a perl script over the top of it to get all such lines and
rate and assign them to people. Worked fairly well and was relatively useful. 

Cheers,

Pete

*------------------------------------------------------*
| "Nearly all men can stand adversity, but if you want |
| to test a man's character, give him power."          |
|       -Abraham Lincoln                               |
*------------------------------------------------------*

Re: A Todo filter

[Nico Seessle <ni...@seessle.de>]

----- Original Message -----
From: "Jason van Zyl" <jv...@periapt.com>
To: <an...@jakarta.apache.org>
Sent: Tuesday, September 19, 2000 7:36 AM
Subject: Re: A Todo filter


> > I don't know what to think of the javadoc-style tags. It makes me
> > wonder if doclets couldn't be used to implement it, though maybe
> > that only works with doc comments? If I used the tags I'd like to
> > be able to define my own fields. For example, here it would be
> > nice to be able to supply the corresponding bug id for Bugzilla
> > when there is one.
>
> I'd like to keep it really simple right now. Gather ideas
> and make something in an couple of hours that produces
> something useful. I need to make a BIG TODO list very
> soon :)
>

You know of http://java.sun.com/products/jdk/javadoc/proposed-tags.html and
http://java.sun.com/products/jdk/1.2/docs/tooldocs/javadoc/overview.html#tag
s ?

Even Generators for C++
(http://www.sylvantech.com/~talin/projects/scandoc/scandoc.html#ttodo) and
Delphi (http://www.time2help.com/online_help/IDH_JavaDocTag_Todo.htm).

I dont't know if this is required to work with JDK 1.1, but in theory you
should be able to use different/future tools if something like @todo is
used. (although the priority is missing from sun's proposal, maybe you
should tell them to include that :-) ). But I don't know if Javadoc is fast
enough? Last time I tried performance seems to be very bad (back in early
1.1).

Oh, I don't know if Javadoc will parse these comments if they don't belong
to a class? Would make it impossible to add todo-comments to single lines of
source then.

Just wanted to be sure you know Sun has thought about it also.

Nico

Re: A Todo filter

[Jason van Zyl <jv...@periapt.com>]

On Mon, 18 Sep 2000, John Lacey wrote:

> Jason van Zyl wrote:
> > 
> > Would anyone be interested in an ant task that
> > would pass through a set of source files and
> > create a project wide TODO list. [...]
> > 
> > /*!
> >  * @desc An Exception should be thrown here
> >  *       instead of triggering a NPE.
> >  * @priority 1
> >  */
> 
> I like this idea a lot. (I don't know of anything like it.) I
> wonder a little why it needs to be an Ant task, though. Couldn't
> it be a stand-alone program, and then either use a java task or
> *maybe* a small wrapper task to call it from Ant?

Yes, it could be a standalone task. I would just like make
it a standard build item.
 
> You seem to be using a ! to indicate these comments. We happen to
> use ??? though I don't remember where I picked that up, and FIXME
> is also popular. In other words, I think that a configurable
> indicator would be needed to make this widely useful. 

I don't know how easy it would be to have configurable
TODO indicators using a generated parser. The /*! */
would make the TODO blobs very easy to parse. I don't
really care what they are, but a clear start and end
of the blobs is required for easy parsing.

> (As an aside, sometimes we put the indicator at the end of the
> comment instead of the beginning. I could trained to avoid that.
> ;-) )

Yes, I'd like to stick to the javadoc type convention.

> Both C and C++ comment styles should be handled.

I would prefer to stick with the single /*! */ 
for simplicity, and you probably can't get a very
good description of what needs to be done in one line :)

> I don't know what to think of the javadoc-style tags. It makes me
> wonder if doclets couldn't be used to implement it, though maybe
> that only works with doc comments? If I used the tags I'd like to
> be able to define my own fields. For example, here it would be
> nice to be able to supply the corresponding bug id for Bugzilla
> when there is one.

I'd like to keep it really simple right now. Gather ideas
and make something in an couple of hours that produces
something useful. I need to make a BIG TODO list very
soon :)
 
> Maybe produce an XML output file that one could use XSLT or
> whatever on to produce the desired final result?

Could produce anything really but XML would probably
probably be a good format. We use StyleBook for the
Turbine and Velocity docs and it has a TODO format.

jvz.

-- 

Jason van Zyl
jvanzyl@periapt.com

Re: A Todo filter

[John Lacey <jo...@vizdom.com>]

Jason van Zyl wrote:
> 
> Would anyone be interested in an ant task that
> would pass through a set of source files and
> create a project wide TODO list. [...]
> 
> /*!
>  * @desc An Exception should be thrown here
>  *       instead of triggering a NPE.
>  * @priority 1
>  */

I like this idea a lot. (I don't know of anything like it.) I
wonder a little why it needs to be an Ant task, though. Couldn't
it be a stand-alone program, and then either use a java task or
*maybe* a small wrapper task to call it from Ant?

You seem to be using a ! to indicate these comments. We happen to
use ??? though I don't remember where I picked that up, and FIXME
is also popular. In other words, I think that a configurable
indicator would be needed to make this widely useful. 

(As an aside, sometimes we put the indicator at the end of the
comment instead of the beginning. I could trained to avoid that.
;-) )

Both C and C++ comment styles should be handled.

I don't know what to think of the javadoc-style tags. It makes me
wonder if doclets couldn't be used to implement it, though maybe
that only works with doc comments? If I used the tags I'd like to
be able to define my own fields. For example, here it would be
nice to be able to supply the corresponding bug id for Bugzilla
when there is one.

Maybe produce an XML output file that one could use XSLT or
whatever on to produce the desired final result?

John L

Re: A Todo filter

[Jason van Zyl <jv...@periapt.com>]

On 19 Sep 2000, Stefan Bodewig wrote:

> >>>>> "JvZ" == Jason van Zyl <jv...@periapt.com> writes:
> 
>  JvZ> I would probably make a small parser using JavaCC.
> 
> Your example looks more as if a custom doclet together with the
> javadoc task could do the trick.

Great! Thanks, I'll take a look at making a doclet.

jvz.
 
> Other than that I'm afraid it would be plain impossible to find each
> and every indicator anybody might be using. Most apache projects have
> FIXME and XXX comments for example.
> 
> With that said: Yes a task like this would be *very* useful but I
> guess you'd either have to make it very complicated and configurable
> or enforce a special notation on the user.
> 
> Stefan
> 

-- 

Jason van Zyl
jvanzyl@periapt.com

Re: A Todo filter

[Stefan Bodewig <bo...@bost.de>]

>>>>> "JvZ" == Jason van Zyl <jv...@periapt.com> writes:

 JvZ> I would probably make a small parser using JavaCC.

Your example looks more as if a custom doclet together with the
javadoc task could do the trick.

Other than that I'm afraid it would be plain impossible to find each
and every indicator anybody might be using. Most apache projects have
FIXME and XXX comments for example.

With that said: Yes a task like this would be *very* useful but I
guess you'd either have to make it very complicated and configurable
or enforce a special notation on the user.

Stefan

Re: A Todo filter

[Jason Dillon <ja...@planet57.com>]

It seems to me that it would be best to create a doclet to do this.  

--jason

On Tue, 19 Sep 2000, Jason van Zyl wrote:

> Hello,
> 
> Would anyone be interested in an ant task that
> would pass through a set of source files and
> create a project wide TODO list.
> 
> I am playing around with Velocity and there
> are so many things to be done, but I'd like
> a TODO document to be made from the source.
> 
> I was thinking something like:
> 
> /*!
>  * @desc An Exception should be thrown here
>  *       instead of triggering a NPE.
>  * @priority 1
>  */
> 
> All of these could be collected for a source
> file and organized by package, sorted by
> priority, location in the file (line #)
> where the work needs to be done.
> 
> Is there already something like this?
> 
> It wouldn't take long to make something like
> this, and I know I would really like it if
> a TODO could be generated every night from
> the sources and made publicly accessible.
> 
> I would probably make a small parser using
> JavaCC.
> 
> Any thoughts?
> 
> jvz.
> 
> -- 
> 
> Jason van Zyl
> jvanzyl@periapt.com
>