Re: Enabling Clang's -Wdocumentation in Frameworks...?
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 > >
Re: Enabling Clang's -Wdocumentation in Frameworks...?
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
Enabling Clang's -Wdocumentation in Frameworks...?
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 | kf...@kde.org | http://kfunk.org signature.asc Description: This is a digitally signed message part.
