2

I want to run some kind of linter or static code analysis on C/C++ code which gives a warning if there is code with missing documentation, for example a function without its doxygen-style documentation coment. In other words, I want to enforce certain code standards. I had a look into clang-tidy and cppcheck, but didn't get very far.

To make it a little bit clearer what I'm expecting - from Python, I'm used to something like this:

$ cat test.py 
def answer():
    return 42
$ python3 -m pylint test.py 
************* Module test
test.py:1:0: C0111: Missing module docstring (missing-docstring)
test.py:1:0: C0111: Missing function docstring (missing-docstring)

------------------------------------------------------------------
Your code has been rated at 0.00/10 (previous run: 0.00/10, +0.00)
finefoot
  • 9,914
  • 7
  • 59
  • 102
  • There's nothing like that for C++ that I ever heard of. – Sam Varshavchik Oct 20 '19 at 00:07
  • C++ is the most complicated general purpose programming language in use today. It's syntax and grammar is several orders of magnitude more complicated than Python. Only a real C++ compiler will have any idea where a particular function begins and ends, in a text file that consists of a bunch of ASCII characters. This is why there are not really that many non-compiler tools that can make any sense of C++ code, in order to do the kind of analysis you're looking for. Yes, it might be possible to make some educated guesses, probably based on indentation, but nothing more than that. – Sam Varshavchik Oct 20 '19 at 00:48
  • 3
    Doxygen itself provides warnings for C++ functions that aren't documented and even for undocumented argument(s) for a documented function. Would that work? – Null Oct 21 '19 at 16:37
  • Yes, I see it print warnings for undocumented functions and parameters when I run it on my code. – Null Oct 29 '19 at 02:15

2 Answers2

5

Clang has the -Wdocumentation option for statically checking Doxygen-style comments. \see https://clang.llvm.org/docs/UsersManual.html.

Also, as @Null mentioned in the comments, the doxygen tool itself will warn of certain documentation issues.

pathfinderelite
  • 3,047
  • 1
  • 27
  • 30
1

I faced this issue recently and I actually used doxygen itself + a custom script to make sure that all the documentation is always present.

In the doxygen config file, enable the following:

WARNINGS               = YES
WARN_IF_UNDOCUMENTED   = YES
WARN_IF_DOC_ERROR      = YES
WARN_NO_PARAMDOC       = YES

# Do not throw errors on warning
# otherwise, it will stop on first
# error
WARN_AS_ERROR          = NO

# It will write all warnings to a
# warning file. Make sure to
# add this to your gitignore
WARN_LOGFILE           = doxy.warn

# Optional
QUIET                  = YES

Now, when you run doxygen command, it will write all errors inside doxy.warn file.

Now, we are going to parse it and throw error if doxygen fails. Here is the shell script that I use (I don't know much about powershell; so, can't provide a snippet for Windows):

doxygen

CURRENT_DIRECTORY=$(pwd)

# If doxy.warn file is not empty
if [ -s "doxy.warn" ]; then
    # Remove the current directory from it to
    # make error paths relative and shorter
    # lines for better readability
    cat doxy.warn | sed "s|${CURRENT_DIRECTORY}|.|"

    # Print number warnings
    echo "Total: $(wc -l < doxy.warn) documentation warnings"

    # Exit with error
    exit 1;
else
    echo "Documentation is valid!"
    exit 0;
fi
Gasim
  • 7,615
  • 14
  • 64
  • 131