Make API Doxygen documentation consistent

[tammyleino]

1 - Isolate all Doxygen comments for APIs to header files.
2 - Make Doxygen style consistent when documenting input/output parameters of APIs.

input parameters should be documented as follows:

@param <parameter> <tab> <description>
@return <description>

[tammyleino]

@arnopo @edmooring

I recommend that we only include APIs in the generated documentation and have some questions about some of the Doxygen markup I found for some routines.

Regarding routines to parse the resource table.

These routines are documented with Doxygen markup in the source files - Are these intended to be APIs? If not, I would like to remove the Doxygen formatting from the function headers:
handle_carve_out_rsc
handle_trace_rsc
handle_dummy_rsc

These are not documented with Doxygen markup at all - If the three above routines ARE intended to be APIs, should these also?:
handle_vdev_rsc
handle_vendor_rsc

static functions

The following static functions are documented with Doxygen markup in the source files instead of header files. Are these intended to be APIs?

rpmsg_virtio_return_buffer
rpmsg_virtio_enqueue_buffer
rpmsg_virtio_get_tx_buffer
rpmsg_virtio_get_rx_buffer
rpmsg_virtio_send_offchannel_raw
rpmsg_virtio_tx_callback
rpmsg_virtio_rx_callback
rpmsg_virtio_ns_callback
rpmsg_get_address
rpmsg_release_address
rpmsg_is_address_set
rpmsg_set_address

virtqueue routines

The following are not static but are documented with Doxygen markup only in the source files - are these intended to be APIs?

virtqueue_create
virtqueue_add_buffer
virtqueue_get_buffer
virtqueue_free
virtqueue_get_available_buffer
virtqueue_add_consumed_buffer
virtqueue_enable_cb
virtqueue_disable_cb
virtqueue_kick
virtqueue_dump
virtqueue_get_desc_size

Anything deemed not an API can maintain its i/o comments within the source code, but modified so it doesn't generate an entry in the final documentation.

[tammyleino]

@arnopo @edmooring As I get further into this, I would like to also make the function description consistent in the function header.

There are numerous ways the function description is formatted throughout the code:

1-

 * elf_identify - check if it is an ELF file
 *
 * It will check if the input image header is an ELF header.
 * 

2 -

/**
 * remoteproc_remove
 *
 * Remove remoteproc resource
 *

3-

/**
 *  @brief	Library major version number.
 *
 *  Return the major version number of the library linked into the application.
 *  This is required to match the value of LIB_VERSION_MAJOR, which is the major
 *  version of the library that the application was compiled against.
 *

Zephyr uses 3, which is what I am recommending.

[arnopo]

Hi @tammyleino

@arnopo @edmooring

I recommend that we only include APIs in the generated documentation and have some questions about some of the Doxygen markup I found for some routines.

Regarding routines to parse the resource table.

These routines are documented with Doxygen markup in the source files - Are these intended to be APIs? If not, I would like to remove the Doxygen formatting from the function headers: handle_carve_out_rsc handle_trace_rsc handle_dummy_rsc

These are not documented with Doxygen markup at all - If the three above routines ARE intended to be APIs, should these also?: handle_vdev_rsc handle_vendor_rsc

static functions

The following static functions are documented with Doxygen markup in the source files instead of header files. Are these intended to be APIs?

rpmsg_virtio_return_buffer rpmsg_virtio_enqueue_buffer rpmsg_virtio_get_tx_buffer rpmsg_virtio_get_rx_buffer rpmsg_virtio_send_offchannel_raw rpmsg_virtio_tx_callback rpmsg_virtio_rx_callback rpmsg_virtio_ns_callback rpmsg_get_address rpmsg_release_address rpmsg_is_address_set rpmsg_set_address

virtqueue routines

The following are not static but are documented with Doxygen markup only in the source files - are these intended to be APIs?

virtqueue_create virtqueue_add_buffer virtqueue_get_buffer virtqueue_free virtqueue_get_available_buffer virtqueue_add_consumed_buffer virtqueue_enable_cb virtqueue_disable_cb virtqueue_kick virtqueue_dump virtqueue_get_desc_size

Anything deemed not an API can maintain its i/o comments within the source code, but modified so it doesn't generate an entry in the final documentation.

Good question! Do we export only user API documentation or document all APIs?
Having only user API exported in Documentation seems to me the good practice. But having header with param/field description in code is also useful.

I can see 2 way of doing this:

• use Doxygen tags for user API and another format for internal API.
• use the \internal tag for sections containing internal API.
  I would favor the latter in order to keep a consistent syntax for all function and structure headers.

@wmamills , @edmooring : any opinion?

[arnopo]

@arnopo @edmooring As I get further into this, I would like to also make the function description consistent in the function header.

There are numerous ways the function description is formatted throughout the code:

1-

 * elf_identify - check if it is an ELF file
 *
 * It will check if the input image header is an ELF header.
 * 

2 -

/**
 * remoteproc_remove
 *
 * Remove remoteproc resource
 *

3-

/**
 *  @brief	Library major version number.
 *
 *  Return the major version number of the library linked into the application.
 *  This is required to match the value of LIB_VERSION_MAJOR, which is the major
 *  version of the library that the application was compiled against.
 *

Zephyr uses 3, which is what I am recommending.

+1 for your recommendation

[arnopo]

@tammyleino
could we consider this issue closed with #478 integration?