Well maybe we should make adding doxygen mandatory for checkin. Some more comments;
- Header files are usually annotated as API documentation, e.g. the consumers of the API will use this. - Source files are usually annotated as internal documentation, e.g. explaining why the code is like this. o I can read the code, so need to explain what the code does, one needs to explain what the intention of the code is. o Yeah that is really hard, but if not done, then the code will start to rust and being replaced by the next developer that did not know what it meant to do. Note that the lack of good API documentation is currently blocking my work in getting the ?application? level code generation working correctly. e.g. I do not know what to call when to make an simple ?binary light?.. Kind Regards, Wouter From: iotivity-dev-bounces at lists.iotivity.org [mailto:[email protected]] On Behalf Of Nash, George Sent: 20 March 2017 22:11 To: C.J. Collier <cjcollier at linuxfoundation.org>; Mats Wichmann <mats at wichmann.us> Cc: IoTivity Developer List <iotivity-dev at lists.iotivity.org> Subject: Re: [dev] IoTivity documentation standards Mats, I am glad that you have brought up some of these issues. I disagree that the efficient doxygen comments page sounds mandatory. However, all of the suggestions probably are best to be followed. (a) Based on recent commits that I have made. There is definitely a strong desire to use the [in], [out] markup. It would probably be wise to add it to the wiki page. (b) There is no convention that I know of. This is an area that could be improved. (c) There is a huge advantage of having the documentation in the headers vs. the source files. The header is the only part that is readable by developers in the distributed sdk. By putting the documentation in the header we are helping developers that use the code. I think using the headers is the correct choice. (d) I have not actually seen this be an issue. Doxygen cannot apply the documentation to anything so it does not end up in the output. I don?t know if this was being over cautious or if it is a real problem. I personally have not seen it in the output. (e) There is some discussion for public vs. private APIs. Unfortunately the discussion somehow got moved over to the maintainers email list (much smaller group that has +2 permission in gerrit.) not the iotivity-dev email list. I have already done some cleanup for the csdk. This is still a work in progress. See: https://gerrit.iotivity.org/gerrit/#/c/17991/ (public API headers), https://gerrit.iotivity.org/gerrit/#/c/17923/ (All headers/code including internal only) Also please don?t use the @internal doxygen tag it does not do what you think it does. All it does it hide the documentation not the class, function, or variable. It is better to use @cond <tag> @endcond. It would good if all the internal documentation used the same tag so it could be included in the internal only documentation. I think the top suggestion for all documentation should be ?check the output? till you actually read the output generated by doxygen you cannot be sure it is doing what you think it is doing. I have had to make some major changes to documentation because it simply was not doing what the developer thought it was doing. I would love to add a doxygen build that would fail if you produce any doxygen warnings but that could be a large task. George From: iotivity-dev-bounces at lists.iotivity.org<mailto:iotivity-dev-bounces at lists.iotivity.org> [mailto:[email protected]] On Behalf Of C.J. Collier Sent: Monday, March 20, 2017 1:50 PM To: Mats Wichmann <mats at wichmann.us<mailto:mats at wichmann.us>> Cc: IoTivity Developer List <iotivity-dev at lists.iotivity.org<mailto:iotivity-dev at lists.iotivity.org>> Subject: Re: [dev] IoTivity documentation standards 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<mailto: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<mailto: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/20170321/b3e77e61/attachment.html>
