Thanks Ashok, I will update the Doxyfile with this information.
George From: Ashok Babu Channa [mailto:[email protected]] Sent: Thursday, March 23, 2017 4:23 AM To: '??? (Uze Choi)' <uzchoi at samsung.com>; Nash, George <george.nash at intel.com>; '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 Hi Uze, Yes connectivity/api is not intended for App developers. Only ../../csdk/connectivity/api/cautilinterface.h (in list) will be useful for them. Others headers in connectivity/api are intended to be used only by RI. Regards, Ashok From: iotivity-dev-bounces at lists.iotivity.org<mailto:iotivity-dev-bounces at lists.iotivity.org> [mailto:[email protected]] On Behalf Of ??? (Uze Choi) Sent: Thursday, March 23, 2017 3:23 PM To: 'Nash, George'; 'C.J. Collier'; 'Mats Wichmann' Cc: 'IoTivity Developer List' Subject: Re: [dev] IoTivity documentation standards Hi Ashok, Can you check the connectivity/api list once more? AFAIK, Originally, this api folder was not intended to App/Service developer. But some APIs are useful to both to IoTivity intenal developer and app developer, they are opened. We can consider header separation for these special APIs. BR, Uze Choi From: Nash, George [mailto:[email protected]] Sent: Thursday, March 23, 2017 12:55 AM To: uzchoi at samsung.com<mailto:uzchoi at samsung.com>; 'C.J. Collier'; 'Mats Wichmann' Cc: 'IoTivity Developer List' Subject: RE: [dev] IoTivity documentation standards Thanks Uze for taking the time to help figure out which header files are intended for the public API: It looks like a few of the headers from your list differ from the list that was in my recent commit https://gerrit.iotivity.org/gerrit/#/c/17991/ The current commit contains all header files in ../../csdk/connectivity/api/ i.e. ../../csdk/connectivity/api/cacommon.h (not in list) ../../csdk/connectivity/api/cainterface.h (not in list) ../../csdk/connectivity/api/casecurityinterface.h (not in list) ../../csdk/connectivity/api/cautilinterface.h (in list) It does not contain the header files in ../../csdk/security/include/internal Let me know if I should update the list of INPUT files for the Doxyfile. George From: ??? (Uze Choi) [mailto:[email protected]] Sent: Tuesday, March 21, 2017 8:29 PM To: Nash, George <george.nash at intel.com<mailto:george.nash at intel.com>>; 'C.J. Collier' <cjcollier at linuxfoundation.org<mailto:cjcollier at linuxfoundation.org>>; '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 I am happy to see meaningful discussion happen so I can expect improvement the doxygen documentation. Step by step, Let?s focus on the External C API first, C++ and Java in sequence. Think about the internal API as next step. Let me suggest document enhancement task as several steps. 0. We can consider to relocate the header file into appropriate folder. 1. filter out which is not intended public API from the header file. 2. fill in the context for function and parameter description on the missed API. 3. review and fix the explanation from sample application view. Even though description is filled with guided way, we are not make sure explanation is enough to understand. ../../csdk/stack/include/ocstack.h ../../csdk/stack/include/octypes.h ../../csdk/stack/include/ocpayload.h ../../csdk/stack/include/ocpresence.h ../../csdk/stack/include/payload_logging.h ../../csdk/stack/include/ocstackconfig.h ../../csdk/connectivity/api/cautilinterface.h ../../csdk/security/include ../../csdk/security/include/internal (This need to be checked again from Randeep) ../../csdk/security/provisioning/include ../../csdk/resource-diretory/include ../../csdk/routing/include ../../c_common/ocrandom/include/ocrandom.h \ ../../c_common/oic_malloc/include/oic_malloc.h \ ../../c_common/oic_string/include/oic_string.h \ ../../c_common/oic_time/include/oic_time.h \ ../../service/easy-setup/inc \ ../../service/easy-setup/enrollee/inc \ ../../service/notification/include \ ../../service/coap-http-proxy/include \ Regarding Mat question, [in] [out] should be mandatory only in the C API, not C++, Java. BR, Uze Choi From: iotivity-dev-bounces at lists.iotivity.org<mailto:iotivity-dev-bounces at lists.iotivity.org> [mailto:[email protected]] On Behalf Of Nash, George Sent: Tuesday, March 21, 2017 7:11 AM To: C.J. Collier; Mats Wichmann Cc: IoTivity Developer List 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 [cid:image001.gif at 01D2A3B0.AE0AA330] [http://ext.samsung.net/mail/ext/v1/external/status/update?userid=ashok.channa&do=bWFpbElEPTIwMTcwMzIzMTEyMjE0ZXBjYXM1cDJlMjQyZjcxZTA5ZWJiMmNiNTRiNjhjYjIxNzlkNGU4OCZyZWNpcGllbnRBZGRyZXNzPWdlb3JnZS5uYXNoQGludGVsLmNvbQ__] -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.iotivity.org/pipermail/iotivity-dev/attachments/20170323/85c65e92/attachment.html> -------------- next part -------------- A non-text attachment was scrubbed... Name: image001.gif Type: image/gif Size: 13402 bytes Desc: image001.gif URL: <http://lists.iotivity.org/pipermail/iotivity-dev/attachments/20170323/85c65e92/attachment.gif>
