TODO/FIXME/XXX + doxygen

[Greg Ercolano]

While doxygen has a nice feature to collect and show our items marked `\todo`
I don't think it's flagging comments marked `TODO:`, `FIXME:` and `XXX:`

Perhaps we should either do a pass at the code standardizing on doxygen commands,
or perhaps doxygen can somehow be coerced to react to those strings.

I can open an issue, but thought I'd bring it up here first.

[Greg Ercolano]

This seems possibly relevant:
https://stackoverflow.com/questions/8535635/can-doxygen-easily-be-configured-to-recognise-todo-and-fixme-lines

[Albrecht Schlosser]

The important difference is that everything flagged with "\todo" has to
be inside a doxygen comment block. Even if it would be possible to use
one of the techniques of said stackoverflow article I still see two
problems:

(1) Sometimes the TODO or FIXME comment is only meant for internal code
changes, maybe a better implementation, cleanup, refactoring etc.. Such
a comment should *not* appear in the (user) documentation.

(2) Doxygen comments are meant to document the *following* function in
most cases. There are different options, but that's what we're usually
using (99% ?). I have no idea where comments like '\\\ \todo ...'
*within* a function (as some of these TODO/FIXME comments are certainly)
would appear in the docs. Would they be related to this function or
maybe the next one?

Another point is that Doxygen \todo items should usually be *done*
before the next release so they don't appear in the user docs. I'm aware
that this has not always been done in the past but that's as I
understand it.

Other simple comments with // TODO or // FIXME will never appear in the
user documentation. You can still search the sources for such comments
though.

That said, Doxygen \todo comments are one thing and other TODO or FIXME
comments are a different thing.

I believe we could or should "standardize" these comments (a paragraph
in the CMP, maybe) to enable easier searching if someone feels inclined
to improve the code or because they know they left such a comment for
later review.

[Greg Ercolano]

On 2020-11-26 17:06, Albrecht Schlosser wrote:
>
> I believe we could or should "standardize" these comments (a paragraph
> in the CMP, maybe)

    Ya, that would probably be wise.. at least as a suggestion.

    Agreed about leaving TODO/FIXME out of the user docs then, but we should probably
    consider part of the release process grepping for these to see if they need to be resolved
    and/or issues created to solve them.