Clean-up Doxygen for all methods in headers

[marthtz]

As discussed in the last iox dev meeting (2021-02-18) Doxygen comments for all methods in all headers need to be checked for completeness and cleaned-up if necessary.

It should look like this

/// @brief
/// @param[in]
///  ...
/// @return

Comment should have:

• A brief description what's done
• Description of all incoming and return values
• Also check that the param[in] name matches the param name in declaration

Ex1:

/// @brief is the service still offered
/// @param[in] self handle of the publisher
/// @return true is the service is offered otherwise false
bool iox_pub_is_offered(iox_pub_t const self);

Ex2:

/// @brief Doing a thing
void doIt();

[dkroenke]

Here are the doxygen guidelines for iceoyx: https://github.com/eclipse-iceoryx/iceoryx/blob/master/doc/aspice_swe3_4/swe_docu_guidelines.md