Lots of doxygen warnings while generating documentation (Junior job!)

Submitted by Olli Salli @oggis

Assigned to Telepathy bugs list

Link to original bug (#41626)

Description

They go to doxygen.log so they don't offend you outright when running make doxygen-doc, but they're there. A lot of them seem to be for doxygen bugs though, like:

/home/oggis/work/telepathy-qt4/TelepathyQt4/account-set.cpp:\47: \warning: no uniquely matching class member found for Tp::AccountSet::Private::Private(AccountSet *parent, const AccountManagerPtr &accountManager, const AccountFilterConstPtr &filter) /home/oggis/work/telepathy-qt4/TelepathyQt4/account-set.cpp:\77: \warning: documented function `void Tp::AccountSet::Private::connectSignals' was not declared or defined.

Although we definitely don't document the private classes at all. And they're declared too, in fact. The signals are defined only by the moc output, though.

For these, we might try and get doxygen to shut up either by fixing it (though the codebase is a bit of a nightmare IIRC), finding the right config option or by the virtue of grep -v.

That would be useful, to stay notified about the real issues making our docs not exactly what we wrote them as. Such as

/home/oggis/work/telepathy-qt4/TelepathyQt4/dbus.h:\40: \warning: Found unknown command \copyright' \/home/oggis/work/telepathy-qt4/TelepathyQt4/dbus.h:\41: \warning: Found unknown command \license'

We should either define them (maybe as no-op-like) or not use them.

/home/oggis/work/telepathy-qt4/build/TelepathyQt4/_gen/constants.h:\924: \warning: unable to resolve link to requestPropertySupportedContentTypes()' for \link command \/home/oggis/work/telepathy-qt4/build/TelepathyQt4/_gen/constants.h:\103: \warning: unable to resolve link to AccountInterface::requestPropertyParameters()' for \link command

Umm, something's wrong with the generated property accessor docs. Should be \ref? Or no doxygen command at all?

/home/oggis/work/telepathy-qt4/TelepathyQt4/abstract-client.cpp:\304: \warning: argument 'c' of command @param is not found in the argument list of Tp::AbstractClientObserver::shouldRecover() const

Yeah so the docs we wrote for that mystically named parameter go to waste. Like also do the ones for params like

/home/oggis/work/telepathy-qt4/TelepathyQt4/contact-manager.cpp:\573: \warning: Found unknown command `\message'

Et cetera. It would be a nice junior job and a reasonably simple improvement to our docs to

1. get rid of the doxygen warnings which make no sense at all
2. fix the remaining ones
3. implement some kind of check (in make check for .1 development versions?) which verifies that all doxymentation works like we intended, to keep the quality up

Version: git master