Improve API headers documentation

[gmarull]

Is your enhancement proposal related to a problem? Please describe.

Driver API headers, i.e. include/drivers/*.h files, have slight differences when it comes to Doxygen docstrings:

• Some have undocumented structures, e.g. https://github.com/zephyrproject-rtos/zephyr/blob/master/include/drivers/lora.h#L22
• Some use @typedef directive (https://github.com/zephyrproject-rtos/zephyr/blob/master/include/drivers/lora.h#L65)
• Some define API using typedef calls https://github.com/zephyrproject-rtos/zephyr/blob/master/include/drivers/lora.h#L61, some don't https://github.com/zephyrproject-rtos/zephyr/blob/master/include/drivers/gpio.h#L412
• Some drivers make API ops internal https://github.com/zephyrproject-rtos/zephyr/blob/master/include/drivers/gpio.h#L386, some don't https://github.com/zephyrproject-rtos/zephyr/blob/master/include/drivers/led_strip.h

In my opinion one of the key points of high-quality code is homogeneity when it comes to coding conventions, including docstrings.

Describe the solution you'd like

• Agree on a standardized way of structuring API headers docstrings (maybe other headers too)
• Clean-up current API headers

Describe alternatives you've considered

N/A

Additional context

N/A

[gmarull]

cc: @carlescufi @nashif

[carlescufi]

cc: @carlescufi @nashif

Thanks for raising this. I think we should do this in the context of the "Guidelines" rework that we've started discussing in the API meetings. First come up with a standardized set of guidelines and then go through the APIs to enforce them. This of course would include the doxygen and style inconsistencies that you refer to.

[nashif]

same #17616

[nashif]

related https://github.com/zephyrproject-rtos/zephyr/issues/6781

[nashif]

same https://github.com/zephyrproject-rtos/zephyr/issues/6810

[martinjaeger]

@carlescufi I suggest to put this on the agenda of next API meeting if possible. I'm happy to support cleaning up some header files once we have decided on a strategy.

Even if we can't immediately come up with a complete "Guideline", just being clear about the point whether internal driver APIs should be exposed in the docs would be very useful already. (in my opinion they should not)

[carlescufi]

API meeting:

Use can.h as a reference, @henrikbrixandersen to update it according to the

Draft guidelines for Doxygen usage:

• All structures/enums shall be documented
• @typedef not to be used unless necessary
• Until #44086 is implemented, use the formatting for driver-facing calls shown in can.h. So this means adding them in COND_HIDDENand using typedefs

[henrikbrixandersen]

44162 removes the @typedef Doxygen commands from the CAN API documentation.