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:
- 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. - 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:
- parameters
yandxare in the wrong order - parameter
zis missing a@param - template parameter
Tis missing a@tparam - 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?