Here are some things that would reduce a lot of repetition day-to-day:
- Automatically "flag" or alert me doxygen blocks where the number of
paramsections does not match the number of arguments in the function declaration below it - Ideally, tell me if the names of the parameters don't match as well
- Flag/alert me to doxygen blocks whose params are missing
[in],[out]or[in,out]. Ideally, auto-fill anything markedconstas[in] - Something to convert between
\and@for sections all at once rather than doing it ~4 times with find and replace. - Something to format the blocks in a pretty way. As an example, here is a simple doxygen block that I consider "unformatted":
/**
* \brief Given a position in the grid, this updates the per-code bounds.
* \param[in] code - The code we are adjusting the bounds of
* \param[in] position1 - The new lower position
* \param[in] position2 - The position of the lower cell within the high-level cell,
* this has a long description that may wrap over a couple lines.
* \return How many positions we had to move
*/
int updateExtents(
const ObjCode code,
const Geo::Point<uint8_t>& upperPos,
const Geo::Point<uint8_t>& lowerPos);
And here's what it looks like with a little touch-up:
/**
* \brief Given a position in the grid, this updates the per-code bounds.
* \param[in] code - The code we are adjusting the bounds of
* \param[in] position1 - The new lower position
* \param[in] position2 - The position of the lower cell within the high-level cell,
* this has a long description that may wrap over a
couple lines.
* \return How many positions we had to move
*/
int updateExtents(
const ObjCode code,
const Geo::Point<uint8_t>& upperPos,
const Geo::Point<uint8_t>& lowerPos);
This is highly subjective, but the descriptions of each parameters are now aligned to the nearest tab, and wrap at that point rather than back at the beginning. I find it makes it a lot more readable.