Wouter, I have been trying to improve the doxygen documentation. https://gerrit.iotivity.org/gerrit/#/c/17569/ - Fixed documentation warnings for cpp-docs https://gerrit.iotivity.org/gerrit/#/c/17543/ - Fixed documentation warnings for c-docs
Although those two commits cleaned up the warnings produced by doxygen there is still a lot that needs to be done. Most of which you have noted. Adding the [in], [out], and [in,out] markup to the parameters is a large task that I am going to start working on. The task is made more difficult since using the wrong markup could be worse than having no markup. The Doxyconfig files also need to be updated. There are a lot of files not currently run through doxygen. Improving the doxygen output has been a side project not my primary task. I work on it when I can but don?t have any time frame for the work. I am happy to work with anyone else that wants to improve the doxygen. If you have a list of files you feel need attention the most I can focus on those. George From: iotivity-dev-bounces at lists.iotivity.org [mailto:[email protected]] On Behalf Of Wouter van der Beek (wovander) Sent: Tuesday, March 7, 2017 11:39 PM To: uzchoi at samsung.com; Omar Maabreh via iotivity-dev <iotivity-dev at lists.iotivity.org>; Macieira, Thiago <thiago.macieira at intel.com>; ??? <glen.kim at samsung.com> Subject: Re: [dev] Smart Home API proposal. Hi All, I did an test for code generation for the node.js layer on top of IOTIvity. This is in OCF github at. https://github.com/openconnectivityfoundation/swagger2x the approach is template based, so the mechanism can work for any language/os/library combination. One just have to write an template for the target. The key of doing this correctly is having an good documented API of the library where the code generation need to generate to. e.g. all calls of an library needs to be documented on API level, e.g. call flows, call descriptions all need to be fully there. This is currently not the case for IOTIvity (C/C++/Node.js ?APIs). This needs to get sorted out quickly. Please start to use doxygen to its full extend: Each header file (or in javascript the callable code) should be fully documented on: - Each call should have full doxygen documentation o Usefull description o Description of each parameter (in and out) - Higher level, we need call sequences o Either in pseudo code or in sequence diagrams. o Where the component fits in the overall stack architecture. I strongly would suggest that from now on each checkin should contain the doxygen documentation. If the header file is completely not documented with doxygen: please do the work for all functions. So that this technical debt is gone within 2-3 months.. Kind Regards, Wouter From: iotivity-dev-bounces at lists.iotivity.org [mailto:[email protected]] On Behalf Of ??? Sent: 08 March 2017 07:01 To: Omar Maabreh via iotivity-dev <iotivity-dev at lists.iotivity.org>; Thiago Macieira <thiago.macieira at intel.com>; ??? <glen.kim at samsung.com> Subject: Re: [dev] Smart Home API proposal. Considering frequent adding and changing resource and property in the real world, code generation should be done again and again during developement which lead generated skelton code to be copied and replaced again. Furthermore code generation is a little bit old style I feel. Recently well abstrated API following less user code is more trendy( this comment does not mean Smart Home API.) According to Younggin comment design goal looks different. Whether code generation or not is othogonal from the main idea of his API proposal. Omar could you explain why IPCA is closer to code generation ? BR Uze Choi --------- Original Message --------- Sender : Omar Maabreh via iotivity-dev <iotivity-dev at lists.iotivity.org<mailto:iotivity-dev at lists.iotivity.org>> Date : 2017-03-08 07:12 (GMT+1) Title : Re: [dev] Smart Home API proposal. Totally agree that code generation is the right solution to this problem which we'd all like to solve. The IPCA api's that are in gerrit right now are a first step in enabling this. Thanks, - Omar -----Original Message----- From: iotivity-dev-bounces at lists.iotivity.org<mailto:iotivity-dev-bounces at lists.iotivity.org> [mailto:[email protected]] On Behalf Of Thiago Macieira Sent: Tuesday, March 07, 2017 10:06 PM To: iotivity-dev at lists.iotivity.org<mailto:iotivity-dev at lists.iotivity.org>; glen.kim at samsung.com<mailto:glen.kim at samsung.com> Subject: Re: [dev] Smart Home API proposal. Em quarta-feira, 8 de mar?o de 2017, ?s 01:31:27 CET, ??? escreveu: > I think making RAML definition is not easy in 3rd party developer's > point of view. they need to know specification to make it again. > therefore, i think this is reasonable proposal which provides API > usability improvement and way to make OCF service and device easily. I don't think the goals are at odds. We do want the easy API. I just don't want *us* to spend time developing it for each and every resource type that OCF comes up with. I'd like us to create a code generator that does that job for us, for current as well as any future resource types. That way, developers won't need to deal with the RAML files or Swagger files. They'll use the generated API. -- Thiago Macieira - thiago.macieira (AT) intel.com Software Architect - Intel Open Source Technology Center _______________________________________________ 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 _______________________________________________ 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 01D29821.5D1389F0] [Image removed by sender.] -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.iotivity.org/pipermail/iotivity-dev/attachments/20170308/e18f4aad/attachment.html> -------------- next part -------------- A non-text attachment was scrubbed... Name: ~WRD000.jpg Type: image/jpeg Size: 823 bytes Desc: ~WRD000.jpg URL: <http://lists.iotivity.org/pipermail/iotivity-dev/attachments/20170308/e18f4aad/attachment.jpg> -------------- 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/20170308/e18f4aad/attachment.gif>
