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/ Some SConscript function on the other hand might be. > 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. > Question 3: > Convention: an official API must to be documented. Should it be documented > only in the header which exposes it? > Or also in the source file that implements it? If the former, is it > confusing to core devs not to have the doc there in > the implementation, and have to refer to a separate file to make sure > impl-doc stay in sync? If the latter, is there a risk of the docs diverging? https://wiki.iotivity.org/api_guidelines says: "All public APIs must be fully documented using doxygen markup in the public header files" It has no such requirement about docygen markup in the source file (nor is there a requirement to preclude it), as that's outside the scope of API guidelines (since the implementation is not the public API per se), but more in the scope of coding conventions. https://wiki.iotivity.org/iotivity_c_coding_standards says: "For all external API elements, comments on classes, structures, enumerations, member functions and member variable declarations must enumerate all behaviors of the element, including error and exceptional conditions. These comments shall conform to the standards of the current documentation tool, Doxygen." I read that the same way, as only being a requirement for "external" things, and as the source files are not published to out/ they're not "external". As such, I have no strong opinion either way as to whether people use doxygen inside source files. The exception is sample code, since sample code is intended to be public and might benefit from additional markup, especially on functions that do not appear in any .h file but are essential to understanding the sample. > Question 4: > A lot of existing doxy markup is, to use the British expression, "dodgy". We > have guidelines for changing the API > implementations, and in theory at least, unit tests ensure the behavior isn't > changed. How do we safely update > documentation without risking saying something different than the > implementation, if the doc is unclear/incomplete > as written? (this may be a procedure question: "XXX maintainer must approve > changes to API docs") I'd be ok with "API maintainer or a language-specific sub-maintainer must approve changes to API docs" > Question 5: > Is the new OC_DEPRECATE* support integrated with the existing deprecation > markers, which are all in the doxygen markup? It should be. George should confirm. -Dave _______________________________________________ iotivity-dev mailing list [email protected] https://lists.iotivity.org/mailman/listinfo/iotivity-dev
