Re: API documentation convention


Gerard Marull Paretas
 

Multiple issues have been raised over time related to this topic. I opened this one ~1y ago: https://github.com/zephyrproject-rtos/zephyr/issues/30466

So to summarize, there are no established rules now. Answers to your questions below:

On Wed, Jan 5, 2022 at 1:14 AM Keith Short via lists.zephyrproject.org <keithshort=google.com@...> wrote:
Is there a preferred convention for documenting APIs?

As a typical example, a driver provides an API structure of function pointers that is filled out by each driver instance.  The driver then provides public routines that simply wraps the function pointers.

e.g.
struct my_driver_api {
    int (*init)(const struct device *dev);
}
static inline my_init(const struct device *dev)
{
    return api->init(dev);
}

My specific questions:
1. Should the driver create typedefs for all the function pointers in struct my_driver_api?  This seems to be common, but there are counter examples (uart.h)

IMO typedefs are redundant and could be deleted. They're likely a result of copy & paste.
 
2. If typedefs are created, should the typedef  or the public routine, or both get documented? i2c.h documents only the public API, not the typedef, pwm.h documents both.

I think that both typedefs and the struct holding the API ops are really internal details that should not be rendered in the Doxygen output. So I'd vote for just documenting the API calls.
 

Regards,
Keith



--

Gerard Marull-Paretas
Teslabs Engineering S.L.
teslabs.com T. +34 622 321 312

CONFIDENTIALITY NOTICE:
The contents of this email message and any attachments are intended solely for the addressee(s)
and may contain confidential and/or privileged information and may be legally protected from
disclosure. If you are not the intended recipient of this message or their agent, or if this message
has been addressed to you in error, please immediately alert the sender by reply email and then
delete this message and any attachments. If you are not the intended recipient, you are hereby
notified that any use, dissemination, copying, or storage of this message or its attachments is
strictly prohibited. 

Join devel@lists.zephyrproject.org to automatically receive all group messages.