Well there should be 2 sets of documents: 1) API level, e.g. annotated header files. (and header files only) - should list the APIs - should list all input parameters + enums - should have an call flow of how to use it - should describe for each function what it does - this info is how to use the stack 2) internal design documentation, e.g. the annotated C/C++ files - should describe for each function HOW it does it. - also the structure of calls, if static functions are used. - this will give any developer the insight of how the stack is build up.
Kind Regards, Wouter -----Original Message----- From: iotivity-dev-bounces at lists.iotivity.org [mailto:[email protected]] On Behalf Of ??? (Uze Choi) Sent: 14 March 2017 07:22 To: Dave Thaler via Iotivity-maintainers <iotivity-maintainers at lists.iotivity.org> Cc: 'IoTivity Developer List' <iotivity-dev at lists.iotivity.org> Subject: Re: [dev] C API docs: which Doxyfile? Hi Ashok, and Randeep, Could you check validation this header file list for public API? If needed share the work with sub maintainer. BR, Uze Choi -----Original Message----- From: ??? (Uze Choi) [mailto:[email protected]] Sent: Tuesday, March 14, 2017 10:46 AM To: 'Mats Wichmann'; 'Nash, George'; 'IoTivity Developer List' Subject: RE: [dev] C API docs: which Doxyfile? C API is the most fundamental language among them, We need to filter out by confirming from each maintainer. (Discovery & Connectivity, Security) Let's debug one by one. ../../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/stack/include/internal/occlientcb.h \ ../../csdk/stack/include/internal/occollection.h \ ../../csdk/stack/include/internal/ocobserve.h \ ../../csdk/stack/include/internal/ocpayloadcbor.h \ ../../csdk/stack/include/internal/ocresource.h \ ../../csdk/stack/include/internal/ocresourcehandler.h \ ../../csdk/stack/include/internal/ocserverrequest.h \ ../../csdk/stack/include/internal/ocstackinternal.h \ ../../csdk/stack/include/internal/oicgroup.h \ ../../csdk/stack/include/internal/oickeepalive.h \ ../../csdk/connectivity/api \ ../../csdk/security/include \ ../../csdk/security/include\internal \ ../../csdk/security/provisioning/include \ ../../csdk/security/provisioning/include/ocprovisioningmanager. h \ ../../csdk/security/provisioning/include/pmtypes.h \ ../../csdk/security/provisioning/include/pmutility.h \ ../../csdk/security/provisioning/include/internal \ ../../csdk/security/provisioning/include/oxm \ ../../csdk/security/provisioning/include/cloud \ BR, Uze Choi -----Original Message----- From: iotivity-dev-bounces at lists.iotivity.org [mailto:iotivity-dev- [email protected]] On Behalf Of Mats Wichmann Sent: Tuesday, March 14, 2017 10:25 AM To: Nash, George; IoTivity Developer List Subject: Re: [dev] C API docs: which Doxyfile? On 03/13/2017 03:08 PM, Nash, George wrote: > You are correct. The current doxygen file is > resource/docs/c-doc/Doxyfile > > https://wiki.iotivity.org/generate_api_doc > > Right now the wiki only includes the instructions on generating the > API doc nothing more. > > I do not know why the files don't set the "OPTIMIZE_OUTPUT_FOR_C" flag. It seems like it should be set. > > There is also a second Doxygen config file devdocs.doxyfile. > > The best I can gather the default Doxyfile is supposed to be for the public headers. While the devdocs.doxyfile is supposed to run across the all of the project files. It looks like both files need to be maintained a little more. The default Doxyfile is definitally including header files that are internal header files. I did do a little cleanup work recently but that was just the minimum work to fix the warnings reported when doxygen was run. The OSWG really wants to improve the documentation but its hard to know where to start when I am a little unclear about which files are public and which are not. There is also desire to improve the param markup to mark in,out values of the params. > > George Yikes... seems like we need to figure out what the "public API" (among the various C, C++, Java, etc. API sets) actually is. How can I help with this? _______________________________________________ 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
