Expanding clang -Wdocumentation flag to catch missing doxygen tags (@param, @tparam, @return)

Viewed 614

I am currently looking into how to enforce our company coding standards using various tools provided by llvm-clang. One of the standards is that each c++ function must have accurate doxygen style documentation.

Note: I am currently using clang v6.0.0, not v9.

First I looked into the clang -Wdocumentation flag, but from my research it is missing a few of my required features:

  1. Although all @params and @tparams in the doxygen are checked for corresponding parameters and template parameters in the associated function, missing @params or @tparams are not caught. I'd like to emit a warning in this case.
  2. I'd also like to emit a warning if the order of the @params in the doxygen doesn't match the order of the parameters in the function (same for @tparams as well.

Next I looked into the clang-tidy, clang-format and other existing clang tools, but could not find anything customizable to meet my use cases.

Lastly I looked into creating my own standalone clang tool, but quickly became overwhelmed by the vast documentation (I am new to the whole clang experience). I tried following quite a few different promising leads, but with no concrete results.

Below is a simple c++ function semi-commented with doxygen:

/// foo function
/// @param y second parameter
/// @param x first parameter
template <typename T>
int foo(int x, int y, int z) {
    ...
}

If I run clang -Wdocumentation foo.cpp on the code above, no errors are generated. I'd like the following errors to be generated:

  1. parameters y and x are in the wrong order
  2. parameter z is missing a @param
  3. template parameter T is missing a @tparam
  4. missing @return

Does anyone know if any existing tools can be customized to meet my requirements? If not, does anyone have any advice for how to approach making my own tool?

0 Answers
Related