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.
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? How about a convention for a simple marker like
// OCAPI: this header contains definitions contributing to the public API
For developer readability, I guess I think it would be beneficial to
have some actual visible marking that something is part of the API in
this relatively complex code base. For example the rather simpler
sqlite uses this format:
#ifndef SQLITE_EXTERN
# define SQLITE_EXTERN extern
#endif
#ifndef SQLITE_API
# define SQLITE_API
#endif
....
SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
SQLITE_API const char *sqlite3_libversion(void);
SQLITE_API const char *sqlite3_sourceid(void);
SQLITE_API int sqlite3_libversion_number(void);
it's a pattern I've seen in some other projects. I'm not making a
proposal, just raising "some kind of marking" as a discussion point -
something in the doxygen markup might work just as well.
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. In the past few days a commit went in to master branch to
enable macros for deprecation marking, and that changed the doxygen
config to predefine some things, but so far only related to those
specific macros.
There's a little bit of discussion of this in a ticket:
https://jira.iotivity.org/browse/IOT-2952
We have some odd conditionals which are not on/off. For example, one
mentioned in the above ticket: in the build scripts, RD_MODE is always
either CLIENT or SERVER, the option does not exist for it to be
undefined. The selected value is then used as a preprocessor define
(that is, -DRD_CLIENT or -DRD_SERVER will be in effect for any build).
So the doxygen "none are defined" mode is definitely wrong for this
case. 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.
-
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?
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")
Question 5:
Is the new OC_DEPRECATE* support integrated with the existing
deprecation markers, which are all in the doxygen markup? The latter
actually produces a page at the moment:
https://api-docs.iotivity.org/latest-c/deprecated.html
but a quick glance at a couple didn't show the use of the new macros
there, so these deprecated-in-docs items don't have the datestamp we
want to keep track of. Some of those might actually be ready for removal
now, if we could find when they were marked deprecated.
_______________________________________________
iotivity-dev mailing list
[email protected]
https://lists.iotivity.org/mailman/listinfo/iotivity-dev
