Patch for \todo command in comment.

[Dmitri Gribenko]

On Fri, Feb 1, 2013 at 2:38 AM, jahanian <fjahanian at apple.com> wrote:
> This is similar to the last patch and supports doxygen's \todo command.
> In this patch I place the <Todo> named tag at the very end after the <Discussion> tags
> (which are for rando comment blocks). Once, placement of this tag is agreed on, I will add test cases.

I don't think this is the correct way to model \todo.  Two points:

(1) we definitely don't want to warn for multiple \todos -- and we
need a test for that.  (So there's no need to change TableGen to add
IsTodoCommand to command properties, and no need to do anything extra
in CommentSema.)

(2) I think that \todo is just a special kind of a paragraph, so we
should not reshuffle it within the long comment.  And what is
important -- Doxygen does not reorder \todos and normal paragraphs.

But we need to model it in XML so that the client can render it
differently.  I see two approaches:

(1) <Para kind="todo">...</Para>
(2) <ParaGroup kind="todo"><Para>...</Para><Para>...</Para></ParaGroup>

(1) maps cleanly to doxygen, since a single \todo contains only a
single paragraph.  (2) is more general, I don't know if we will
actually need it, but it maps better onto our AST.

Actually, I think (1) is better, for now.  We can always introduce (2)
for groups of more than 1 <Para>.

We can easily apply the same logic for other commands like \note etc.
But there are \author, \bug, \copyright (maybe others) that are
different -- they don't feel like a part of the description, and their
semantics suggest that they can be reordered (even if doxygen is not
doing that now).

Dmitri

-- 
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/