AcademySoftwareFoundation
Update Public Header Documentation to Doxygen Style
We discussed this at the 2020-11-13 documentation working group meeting. The first deliverable for this issue should be to take one of the public headers (or even a section of it), put it into Doxygen style, and present the output (as it would appear in the documentation) for review by the community.
One issue to be decided is how verbose to make it. The original OCIO headers had a very succinct style where many arguments, functions, and methods whose meaning was obvious were not documented. Do we want to continue with this style or make it more verbose?
I think if a function is clearly named and has detailed type info it can remain succinct. If however there is any ambiguity about what a class or function does, or how it is intended to be used, we should document it with adequate verbosity to understand it without having to reach out to the community for explanation. Not that there's anything wrong with asking for help/clarification in the community, but it would be good to strive for understanding in isolation if possible.
I volunteered at that 2020-11-13 documentation working group meeting to take a stab at this... and I've been procrastinating ever since :)
I have zero experience with doxygen, but I'm definitely willing to put the work in. Barring no objections, I'll try to have at least part of one of the headers converted and rendered for the next time we meet.
And I agree with Michael -- speaking as someone who's been able to grok much of the new Python API pretty much solely from function and argument names and type info (and having had experience with the OCIO-1 API), I believe much of the API is sufficiently "self-documenting". The only major things that I couldn't easily figure out had to do with creating GPUProcessors and doing stuff with metadata; and it's been a while since I've last tried. And just in general, I don't really understand what purpose the custom key/value mappings are supposed to serve for FileRules, but I didn't have any trouble figuring out how to set / get them.
It might be nice to add usage examples in some of the docstrings, maybe for some of the overloaded functions, or to highlight special properties -- e.g., dict-like behavior for modifying Context keys and vars.
