Rework docstrings to have consistent style

[christophfroehlich]

It would be great to be consistent with the style of the existing docstrings, i.e. start the sentence with a verb for "brief". For example, I would put it here

/**
 * @brief Publish the state of the controller manager.
 * 
 * The state includes the list of controllers and the list of hardware interfaces along with their states.
 */

However, I realize that we have already different docstring styles in this file. An example of another style is:

/// A method to register a callback to be called when the list is switched
/**
* \param[in] callback Callback to be called when the list is switched
*/

Is it intentional to have these different styles? @christophfroehlich

Originally posted by @Maverobot in #2006 (comment)