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

[Allen Winter]

On Thursday, January 05, 2017 08:01:53 PM Kevin Funk wrote:
> Heya,
> 
> we all like up-to-date apidocs, right.
> 
I would like to point out that the EBN has been providing pretty reports for doxygen problems for many years already.
Or had been, before the frameworks days.

One such example from KDE4: http://ebn.kde.org/apidocs/apidox-kde-4.x/kdelibs-kdeui.html

I can't speak for the current apidox maintainers if they are interested in bringing back
this capability for frameworks.   or indeed if anyone found the EBN reports useful.


> 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
> 
>