[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-frameworks-devel
Subject:    Re: Enabling Clang's -Wdocumentation in Frameworks...?
From:       Allen Winter <winter () kde ! org>
Date:       2017-01-05 23:21:05
Message-ID: 4316647.58lV5Q9mfq () zazzy
[Download RAW message or body]

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


[prev in list] [next in list] [prev in thread] [next in thread]