doc: doxygen: add driver_api alias to describe driver API #82117
Conversation
kartben
force-pushed
the
driver_api_doxy
branch
from
5ae6eee to
0f3ec09
Compare
|
+1 for automating documentation, perhaps add a reference to the device driver model? |
| "supervisor=\qualifier supervisor" \ | ||
| "driver_api{1}=\brief \htmlonly <span class=\"mlabel\">Driver API</span> \endhtmlonly \1 driver API \ | ||
| \details This is the mandatory API any \1 driver needs to expose." |
There was a problem hiding this comment.
I think calling this "Driver API" is a bit confusing. These are "driver ops", consumed by the actual driver/interface API. For now, we've kept this internal (INTERNAL_HIDDEN), but I think they should be part of first its own header and then its own Doxygen page. Many consumers of the driver/interface API do not care about how it is implemented behind the scenes, so it just clutters the main page. Also, we need to be careful about using @copydoc because there are many situations where there's no 1:1 mapping between the driver/interface API and the op it calls. A simple example is with optional ops: driver/interface API will document @retval -ENOSYS if not implemented, whereas the op won't have it.
|
This pull request has been marked as stale because it has been open (more than) 60 days with no activity. Remove the stale label or add a comment saying that you would like to have the label removed otherwise this pull request will automatically be closed in 14 days. Note, that you can always re-open a closed pull request at any time. |
kartben
force-pushed
the
driver_api_doxy
branch
from
0f3ec09 to
cc4b232
Compare
|
This pull request has been marked as stale because it has been open (more than) 60 days with no activity. Remove the stale label or add a comment saying that you would like to have the label removed otherwise this pull request will automatically be closed in 14 days. Note, that you can always re-open a closed pull request at any time. |
This new alias helps describe the driver API as part of the public documentation, while still making it visually distinguishable so that device driver developers can quickly identify/access them. Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This illustrates how one can document driver API by migrating a few subsystems to the new driver_api Doxygen alias. Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
|
A new attempt at trying to provide public documentation for the driver API that device driver developers need to implement.
https://builds.zephyrproject.io/zephyr/pr/82117/docs/doxygen/html/group__adc__interface.html
https://builds.zephyrproject.io/zephyr/pr/82117/docs/doxygen/html/structadc__driver__api.html