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

[Martin Gräßlin]

Am 2017-01-05 20:01, schrieb 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.

sounds super useful! If we don't get the doc errors fixed till next 
GCI... could be nice tasks

Cheers
Martin