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
