Sorry if this seems to ramble a bit, there are several questions inline. We have a wiki page for doxygen markup in the source tree:
https://wiki.iotivity.org/efficient_doxygen_comments Despite the title of the page ("efficient use"), it starts out sounding very "mandatory" (highlighting mine): === For all external API elements, comments on classes, structures, enumerations, member functions and member variable declarations _must_ enumerate all behaviors of the element, including error and exceptional conditions. These comments _shall_ conform to the standards of the current documentation tool, Doxygen. === Is this page to be considered the official documentation standard, then? Note that Doxygen intentionally leaves a lot of room for flexibility, just saying follows their standards is a little imprecise. Some of the important choices are indeed pinned down in the "Breakdown" section, like the commenting style, which is to use the javadoc style of "/**" as an introducer for a markup comment block. A couple of questions: (a) is the (optional to doxygen) markup of the "direction" of a parameter mandatory? This is the [in] and [out] or both in lines like this: * @param[in,out] header Pointer to the octet array that will * contain the generated header. (b) is there any convention for the "brief description"? We're told not to use @brief, because the JAVADOC_AUTOBRIEF flag shall be set. That means that a space after the first period, not just a newline after the first period, ends the brief description. I'm not sure people are remembering that, as an aside. I think it would be better if our internal convention where still to use a newline after the end of the brief to make it more clear. When you push to gerrit you get complaints if the first line of the commit msg is too long... is there a similar convention (not officially enforced obviously) for doxygen brief? (c) We appear to be following a convention of doing the markup in the header rather than in the code implementation. Make that explicit? I have no preference, but note doxygen's own docs suggest there might be an advantage to keeping it closer to the implementation so developers don't forget to update. (d) due to the use of the Javadoc comment block style being mandatory, the wiki page calls out: === Copyright and other blocks must not accidentally start with a line of asterisks such as one beginning ?/*****...?. === There are actually a lot of blocks in the source tree that DO have that sequence and are not doxygen markup blocks. There are a lot of files that use slightly obscure ways around it (e.g. /* *****), but a lot that don't. Is this something that ought to be cleaned up? (I don't have proof that it actually harms anything, but someone put that line into the wiki page for a reason, presumably). (e) That leads to a slightly bigger topic - there's a lot of documentation of content that is not intended to be part of the public API - which is great, I have no trouble with internal APIs also being documented, that's all to the good. The problem is you often can't tell when you look at a file whether it's intended internal or public. Right now, that information is in a list of files (or directories) in the INPUT sections of the c-doc/Doxyfile and cpp-doc/Doxyfile, and a previous discussion shows we're not entirely sure those have exactly the correct list. Should there be an IoTivity markup convention that indicates a file contains ALL internal interfaces? Doxygen has an @internal option, but it's block based - the scope ends when the comment block ends (the way around that is to use @section, then @internal; iotivity does not use @section at all, it only appears in mbedtls which is an extlibs project). I'm thinking more of something for a human reader of the code. I don't know if there are files that mix internal and external elements, are those required to be marked with internal? @internal appears only twice in the current codebase (both in csdk/connectivity/src/bt_le_adapter/linux).
