Inline [geo]
-----Original Message-----
From: [email protected]
[mailto:[email protected]] On Behalf Of Mats Wichmann
Sent: Friday, January 12, 2018 10:19 AM
To: IoTivity Developer List <[email protected]>
Subject: [dev] a few more API questions (doc, mainly). long-ish.
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.
[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.
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.
[geo] I think that we should document all of the function/classes even the ones
that show up in the macros. The documentation should indicate that the macro
is needed to use the function. I was the one that added the macro expansion
for the deprecated macros. That macro expansion actually causes doxygen to
think that the macro does not exist. The OC_DEPRECATED macro is placed just
before the function being deprecated. This caused doxygen to apply the
documentation to the macro not the function. The macro expansion made it
document the function as expected. Doxygen macro expansion could be improved
for things like CLIENT or SERVER, and RD_MODE.
-
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?
[geo] I don't know the official stance but I think the documentation should be
required in the header files. The documentation can be copied to the source
for developer convenience but it is not what is read by doxygen. The header
files should contain the official documentation. If there is fear of the docs
diverging then just remember the header documentation is the one that ends up
being in the API docs.
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")
[geo] I don't think there is anyone that is assigned as the approver for API
docs. Dave Thaler should probably be included (he may not think this is part
of API guidelines so I will let him chime in.). Also someone that has a good
understanding of Doxygen would be good. Someone like myself or you.
Unfortunately we mush rely on the original developers a lot to document their
own code. We all know sometimes documentation is the last thing on a
developers mind and they will typically do the minimum. I encourage any
improvements in documentation by any developer that feels the understand the
headers enough to improve the 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.
[geo] Unfortanatly I don't know a way to tie the OC_DEPRECATED macro to the
doxygen markup. The responsibility is kindof on the developer to use both the
@deprecated doxygen tag and the macro. The tag is for the documentation and the
macro is for the compiler. If we want to take the time we could find the dates
that things were deprecated using git history. We don't actually have an
official deprecation policy for when deprecated headers will be removed. I
would like to have an official policy. Something related to amount of time
like 2 years or number or releases like will be available for the next two none
point releases (i.e. it was deprecated in 1.2 it will still be available to 1.3
and 1.4 but can be removed in 1.5 or later). I admit using the OC_DEPRECATED
macro was inspired by the AllJoyn projects deprecation macro.
_______________________________________________
iotivity-dev mailing list
[email protected]
https://lists.iotivity.org/mailman/listinfo/iotivity-dev
_______________________________________________
iotivity-dev mailing list
[email protected]
https://lists.iotivity.org/mailman/listinfo/iotivity-dev
