Is there something like a linter/formatter/correctness checker for Doxygen blocks for C++?

Viewed 242

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 param sections 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 marked const as [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.

0 Answers
Related