@todo tag

[GoogleCodeExporter]

How about a tag for indicating the item requires additional work of some
kind, maybe with an optional type, priority, and/or designated person (for
team projects) as well as a description?

That would seem like an ideal use for extracting this information rather
than forgetting about such to-dos--to-dos which may sometimes be more
critical than those explicitly filed in an issue tracker...

Original issue reported on code.google.com by bret...@gmail.com on 25 Aug 2009 at 10:02

[GoogleCodeExporter]

I think you can already do this with custom tags. For example, I have a custom 
@binding tag that didn't need 
any support by the core of jsdoc-toolkit. However, this would only address 
@todo tags inside the primary doc 
comment -- e.g. inside the class definition.

What I do in my template is the following:

    <!-- Bindings summary -->
    {!
        var bindings= data.comment.getTag("binding");
        bindings= bindings.sort(makeSortby("name"));

    !}
    <if test="bindings.length">
        <a name="bindings"></a>
        <h3>Bindings</h3>
        <ul>
            <for each="member" in="bindings">
                <li><a href="#binding-{+member.name+}">{+member.name+}</a></li>
            </for>
        </ul>
    </if>

The problem with @todo is you'd need to cycle through them for nearly 
everything. Unless you made a policy 
decision that they merely apply to top-level symbols: classes, functions, and 
properties.

Original comment by jwmetrocat@gmail.com on 26 Aug 2009 at 4:34

[GoogleCodeExporter]

jwmetrocat +1

Original comment by micmath on 12 Sep 2009 at 6:25

• Changed state: WontFix

[GoogleCodeExporter]

Ok, it's cool to have a solution spelled out for that (thanks jwmetrocat, btw), 
but
as in my other suggestions, I'm first and foremost interested to see useful
conventions so that certain tags which would be useful across projects could 
have the
same custom code built for it (even if not treated specially by JSDocToolkit), 
and we
as developers can just use the same conventions across projects. It's easy for 
me to
add custom code myself, but it's not easy for me to establish on my own loosely
standard conventions. :)  

I might suggest adding also an optional target field (e.g., to do by a given 
version
number, date, etc.) which I think could be useful too if you were open to it.

Original comment by bret...@gmail.com on 13 Sep 2009 at 11:30