| |
| |
On 11/26/20 6:22 PM Greg Ercolano wrote:
On 2020-11-26 08:36, Greg Ercolano wrote:
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.
This seems possibly relevant:
https://stackoverflow.com/questions/8535635/can-doxygen-easily-be-configured-to-recognise-todo-and-fixme-lines
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.
--
You received this message because you are subscribed to the Google Groups "fltk.coredev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to fltkcoredev+unsubscribe@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/fltkcoredev/dfd1742f-f72b-6efc-ad3c-d5f724186336%40online.de.
[ Direct Link to Message ] | |
|
| |
