Hello Mats, Having not participated in the documentation of the API to date, I am certainly not an authority on the matter. But I'll give my two cents anyway!
First, the questions regarding wiki page contents might be best directed to Jon A. Cruz, the author of the wiki page. I've CC'd Jon so that he's aware of the situation. I understand that he may or may not presently have a stake in work on IoTivity. Second, I would recommend that a JIRA issue be opened to track API documentation and that the JIRA issue number be referenced in the wiki page. This will lend some credibility to the work and allow interested parties to review the discussion. Cheers, C.J. On Mon, Mar 20, 2017 at 11:15 AM, Mats Wichmann <mats at wichmann.us> wrote: > 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). > > > _______________________________________________ > iotivity-dev mailing list > iotivity-dev at lists.iotivity.org > https://lists.iotivity.org/mailman/listinfo/iotivity-dev > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.iotivity.org/pipermail/iotivity-dev/attachments/20170320/c4a724a1/attachment.html>
