Wouter, Just out of curiosity.. This code generation tool you're working.. Is it public or private?
regards, Thiago On Tue, Mar 21, 2017 at 12:01 PM, Wouter van der Beek (wovander) < wovander at cisco.com> wrote: > 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: > iotivity-dev-bounces at lists.iotivity.org] *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 > <iotivity-dev-bounces at lists.iotivity.org>] *On Behalf Of *C.J. Collier > *Sent:* Monday, March 20, 2017 1:50 PM > *To:* Mats Wichmann <mats at wichmann.us> > *Cc:* IoTivity Developer List <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> 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 > > > > _______________________________________________ > iotivity-dev mailing list > iotivity-dev at lists.iotivity.org > https://lists.iotivity.org/mailman/listinfo/iotivity-dev > > -- *Thiago Guedes Cunha de Moura* Graduando em Ci?ncia da Computa??o Instituto de Ci?ncias Exatas e Biol?gicas - Universidade Federal de Ouro Preto cel.: (31)99484-9864 -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.iotivity.org/pipermail/iotivity-dev/attachments/20170321/1ed74e8e/attachment.html>
