Clean up OpenEXRCore doxygen comments #1130
Conversation
* Fix improper use of \ref, etc * Fix various warnings * Make consistent use of punctuation, capitalization, and verb tense * Add entries to reference section in OpenEXRCoreAPI.rst to get proper references. Signed-off-by: Cary Phillips <cary@ilm.com>
| /** @file */ | ||
|
|
There was a problem hiding this comment.
Why did you put the @file markers, if you don't aren't generating per-file docs and you don't have any file-level comments?
There was a problem hiding this comment.
While searching for why things weren't showing up, I came across this:
https://www.doxygen.nl/manual/docblocks.html#specialblock
Attention
Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined. In other words, there must at least be a
/*! \file */
That said, I think I resolved all the issues that led me to add those lines, and I'm not sure they are, in face, necessary, so I may be misinterpreting that statement.
There was a problem hiding this comment.
Wow, I didn't know that. I retract my question.
I wonder what counts as "global." Maybe the reason that I've never bumped into this is that I'm working in C++ so everything is technically in a namespace, and thus not global? But for these C bindings, there's no enclosing namespace?
* Fix improper use of \ref, etc * Fix various warnings * Make consistent use of punctuation, capitalization, and verb tense * Add entries to reference section in OpenEXRCoreAPI.rst to get proper references. Signed-off-by: Cary Phillips <cary@ilm.com>
* Fix improper use of \ref, etc * Fix various warnings * Make consistent use of punctuation, capitalization, and verb tense * Add entries to reference section in OpenEXRCoreAPI.rst to get proper references. Signed-off-by: Cary Phillips <cary@ilm.com>
references.
Signed-off-by: Cary Phillips cary@ilm.com