> I don't know if it's correct for any headers to be included in both doxygen > API lists, but here is the duplicated set:
If the C APIs are likely to be used in the C++ programs then it does make since for the header to be in both C and C++ doxygen. Figuring out which headers should go in both should probably be discussed as well. As a general rule we don't want to force the C++ programmer to jump back and forth to the C and C++ API documentation. So C headers that are used in C++ programs would get included in the C++ Doxygen output. It will be optimized as C++ code which will sometimes produce less than ideal documentation. > I hate to ask for "let's go over this whole list again", but I think we need > to. Do install rules need to be added for all of the above, or are there some > that accidentally crept in to the API lists for doxygen? Please ask away this is the only way this will be improved. The API lists for doxygen was done by me with similar discussion to the one we are having now. I tried really hard to only include headers that were installed but there was a lot of conversation back and forth and I likely made mistakes. I was focusing more on the errors produced when running Doxygen. Which does mean we probably got some headers that should not have been included. As you have clearly indicated. My first instinct is to see if we can removed the not installed headers from the doxygen output. If Doxygen reports errors we work from there. George -----Original Message----- From: Mats Wichmann [mailto:[email protected]] Sent: Sunday, January 14, 2018 7:57 AM To: Nash, George <[email protected]>; IoTivity Developer List <[email protected]> Subject: Re: [dev] a few more API questions (doc, mainly). long-ish. Doggedly, worrying away at this... > Question 1. How *do* you determine the official API list? Is it purely > determined by the list of headers? Which is the correct list of headers? > For example, doxygen has a list of headers, sometimes called out by name like: > > INPUT = . \ > ../../csdk/include/octypes.h \ > ../../csdk/stack/include/ocstack.h \ > > but sometimes less precisely called out by directory: > > ../../csdk/security/include \ > ../../csdk/security/provisioning/include \ > ../../csdk/security/provisioning/include/oxm \ > ../../csdk/security/provisioning/include/cloud \ > > the directory form seems a little less precise, but perhaps it's good enough. > is the API list "what is published on the documentation page"? > if so, we need to do a better job of categorizing/grouping, because it is > hard to sort out from the website docs. > [geo] I updated the list of directories that ends up in the APIs. This was a > while ago but I sent the list of directories out to this email list and got > feedback from many of the developers. (mostly Samsung, Microsoft, and Intel) > The general rule I used was if the header is installed to the out directory > at build time it is a public API and should be in the documentation. If the > header should not be part of the documentation it should be in an internal > folder. As long as we don't use recursive directory search option in the > Doxygen config listing the directory should be good enough as long as > developers are carful to use the internal folder. So as of right now, I'm counting the headers in the path out/linux/x86_64/debug/deploy/include after doing a "scons {buncho-options} install", and I get 89, of which seven are in "experimental" subdirectories, so 82 (77 .h and 5 .hpp). I'm also counting the lines from the log of the C and C++ doc builds that look like this, indicating doxygen used them when generating the docs: Generating docs for file base64.h... and I get 45 for c-doc and 57 for cpp-doc, which is 102. If I then remove duplicates between those two it goes down to 96. So it appears we have gone back out of sync between the two methods, with the docs currently picking up more headers (it looks like quite a few things that are clearly API are not getting installed) I don't know if it's correct for any headers to be included in both doxygen API lists, but here is the duplicated set: resource/csdk/include/octypes.h resource/csdk/stack/include/ocstackconfig.h service/easy-setup/inc/escommon.h service/notification/include/NSCommon.h service/notification/include/NSConsumerInterface.h service/notification/include/NSProviderInterface.h All of those have 'extern "C"' wrapping, so I'll assume it is an error for those to be included in the C++ list. >From the C++ doxygen list, these headers are not installed by "scons install": BundleActivator.h NOT INSTALLED BundleResource.h NOT INSTALLED NotificationReceiver.h NOT INSTALLED NSAcceptedConsumers.h NOT INSTALLED NSAcceptedProviders.h NOT INSTALLED NSMediaContents.h NOT INSTALLED NSTopic.h NOT INSTALLED ProtocolBridgeConnector.h NOT INSTALLED ProtocolBridgeResource.h NOT INSTALLED ResourceContainerBundleAPI.h NOT INSTALLED SoftSensorResource.h NOT INSTALLED >From the C doxygen list, these are not installed: base64.h NOT INSTALLED cacommon.h NOT INSTALLED cautilinterface.h NOT INSTALLED CoapHttpMap.h NOT INSTALLED CoapHttpParser.h NOT INSTALLED iotvticalendar.h NOT INSTALLED occertutility.h NOT INSTALLED occloudprovisioning.h NOT INSTALLED ocprovisioningmanager.h NOT INSTALLED ocsecurity.h NOT INSTALLED oic_malloc.h NOT INSTALLED oic_string.h NOT INSTALLED oic_time.h NOT INSTALLED oxmjustworks.h NOT INSTALLED oxmmanufacturercert.h NOT INSTALLED oxmpreconfpin.h NOT INSTALLED oxmrandompin.h NOT INSTALLED oxmverifycommon.h NOT INSTALLED pbkdf2.h NOT INSTALLED pinoxmcommon.h NOT INSTALLED pkix_interface.h NOT INSTALLED pmtypes.h NOT INSTALLED pmutility.h NOT INSTALLED rd_database.h NOT INSTALLED rd_server.h NOT INSTALLED routingmanager.h NOT INSTALLED routingmanagerinterface.h NOT INSTALLED routingmessageparser.h NOT INSTALLED routingtablemanager.h NOT INSTALLED routingutility.h NOT INSTALLED srmutility.h NOT INSTALLED utils.h NOT INSTALLED I hate to ask for "let's go over this whole list again", but I think we need to. Do install rules need to be added for all of the above, or are there some that accidentally crept in to the API lists for doxygen? Incidentally, is there any reason why the "install" directory for headers should not be flat? _______________________________________________ iotivity-dev mailing list [email protected] https://lists.iotivity.org/mailman/listinfo/iotivity-dev
