Enabling Clang's -Wdocumentation in Frameworks...?

[Kevin Funk]

Heya,

we all like up-to-date apidocs, right.

I was pondering whether it would be feasible to globally activate Clang's -
Wdocumentation warning in KDEFrameworkCompilerSettings.cmake in ECM, but we're 
running into too many issues at the moment, thus I ditched the idea.

In case you don't know -Wdocumentation is a feature from Clang to analyze 
doxygen-style comments in source code and thus to check for invalid apidocs 
[1].

Excerpt from my scan today (I just did -DCMAKE_CXX_FLAGS=-Wdocumentation) on 
all of KF5:

  .../kf5/attica/src/accountbalance.h:78:15: warning: parameter 'balance' not 
found in the function declaration [-Wdocumentation]
  .../kf5//attica/src/accountbalance.h:78:21: warning: empty paragraph passed 
to '@param' command [-Wdocumentation]
  .../kf5//attica/src/activity.h:86:15: warning: parameter 'id' not found in 
the function declaration [-Wdocumentation]

With -Wdocumentation enabled I get around 1000 of unique compiler warnings in 
KF5 code; I've uploaded the full log to pastebin for reference:
  https://paste.kde.org/p6r1o1m5j (one year lifetime)

tl;dr: If someone is super bored he could go through those warnings and fix 
them -- only then we could enabled -Wdocumentation globally...

Would be nice to have though. I've just enabled it for all of kdevplatform/
kdevelop.

Cheers,
Kevin

[1] http://clang.llvm.org/docs/UsersManual.html#comment-parsing-options

-- 
Kevin Funk | kfunk at kde.org | http://kfunk.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 163 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-frameworks-devel/attachments/20170105/f5074c27/attachment.sig>