On 01/12/2018 12:15 PM, Dave Thaler wrote: > My view, as API maintainer... > > Mats writes: >> 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? > > Yes, the correct list is the set of .h files copied to the out/ directory by > the build. > >> Is there anything other than human review that keeps the list of >> headers-in-code-which-contain-API in sync with what is given to the doxygen >> config? > > I don't know but if not then it would help if we had tooling to ensure > consistency between the docs and the set of headers copied to out/ > >> How about a convention for a simple marker like >> // OCAPI: this header contains definitions contributing to the public API > > That's not sufficient to ensure consistency with what's copied to out/
agree, but it's still more than "ask [insert name of expert] if this file should be considered part of the API" > Some SConscript function on the other hand might be. could eventually look at that if people think it's worthwhile. > >> Question 2: >> Continuing with "what is the API", some places in public headers are >> conditional. What does that mean to the app developer? >> >> As of a few days ago, doxygen would eliminate all of these, and they don't >> appear in the generated docs, because it does not predefine anything when >> scanning headers. > > Sounds like a bug (or design flaw) to me. All public APIs should be > documented. > All APIs in a public header file are public, even if they're ifdef'ed. > Presumably the intent is that some apps will define them. > >> In any case, it's unclear what it means if an API is only public-official if >> certain things are defined at build time. Should the reading be "if it is >> conditional, it is not in the API"? >> In that case, should such interfaces be pushed over to internal or some >> other place that makes it more clear they're not official? See also end of >> Q #1. > > If the intent is that some apps need them, then they're public (even if > conditional)and documented. > Things not intended for apps to consume should never be in public headers to > begin with. For what it's worth, I agree. In other projects I've argued for "if it's in the API, the prototype is always defined, not #ifdef'd. if the API is truly conditional, in the 'not' case you provide a stub which immediately returns an error, preferably one which can be interpreted as 'Not Implemented'". I've even won that argument on occasion :) _______________________________________________ iotivity-dev mailing list [email protected] https://lists.iotivity.org/mailman/listinfo/iotivity-dev
