Omr: Doxygen comments in headers

[mstoodle]

As @fjeremic pointed out in #795 :

"It may be a good idea to write the Doxygen documentation in the header files where the interface for the function is defined so that consumers of the library who are including the header files have the documentation that comes with them. The details of the implementation should go into the object files.
...
This may be up to debate though and we should collectively as a group decide this for consistency reasons."

I agree it's worth some discussion, so I'm opening this issue for people to weigh in.

[mstoodle]

Personally, I find multi-line Doxygen comments for each member function in the public API of a class to introduce a lot of clutter into the header file, which makes it harder for me to quickly find things. So the direction I took with the JitBuilder files was to put these comments into the C++ files.

But I'm curious to hear others' opinions as I'm nowhere near "religious level of attachment" on this viewpoint.

[mgaudet]

IMO: Brief descriptions of functions in header files are a good thing. Longer descriptions belong in the .cpp files.

[fjeremic]

I'm in favor of having consistency. My case for having them in the header files is that due to the heavy usage of inheritance / extensible classes in OMR we would end up duplicating quite a lot of documentation if each implementor of an interface defined by a header file documented the said interface in the cpp files.

Another issue as mentioned in #795 is that for statically linked libraries the documentation would be non-existent. For example consider a VM consuming a JIT compiler built on top of OMR compiled as a dynamically linked library and making decisions based on APIs exported by the JIT library. All the VM would have is a DLL and a bunch of header files specifying the interface. They would be missing documentation in such case.

[mstoodle]

For reference, the current coding standard documents the following on this topic (possibly there are other relevant sections, I could not motivate myself to rigourously search the whole thing):

Comment function parameters clearly

• A function declaration is preceded by a strategic comment.
• Function comments go in header files for non-static functions. Do not duplicate the comment in the C file.
• The function design intent is described by the comments, such that the reader would have a good shot at reimplementing the function if the source were not available.
• Function comments use Doxygen format.
• Describe all parameters and return values.
• Always indicate units or quantity type where appropriate (e.g. bytes, megabytes, percent, ratio).
• The main point of commenting parameters is to document the responsibilities of the caller (e.g. that it has to free memory at some time).
• If a function uses or modifies global data, this is documented in the function comment.
• Keep comments simple and clear.

Of course, not all files follow these recommendations, which seem to favour putting as much information as possible into the header at function declaration points.

[fjeremic]

Great find @mstoodle! I think the contribution guides are there for new code being contributed. There is no doubt we have a lot of refactoring work for pre-existing code. Of course all of this is subject to change as we can collectively decide to modify the coding standard (or pick an already existing one as discussed in #350).

Would be good to hear other peoples opinions on the topic at hand.

[mstoodle]

Given the coding standards already describe what should be commented on in the header (and I think those recommendations make sense) the only open question here is whether the comments should be in Doxygen style.

There has been no dissent (over the last 3 years!) so perhaps we should just say that Doxygen header file comments are part of the recommended aspiration for new code (and can be retrofitted into existing code as we touch things) ?

[mstoodle]

After discussion on the architecture meeting, we agreed that we're basically doing this already, although we currently are not regulating the style of Doxygen comments and we aren't automatically generating Doxygen output. We'll open new issues to propose a style to be used and to discuss the issues around generating the docs. This issue can be closed.