Bug 41626

Summary: Lots of doxygen warnings while generating documentation (Junior job!)
Product: Telepathy Reporter: Olli Salli <ollisal>
Component: tp-qtAssignee: Telepathy bugs list <telepathy-bugs>
Status: RESOLVED MOVED QA Contact: Telepathy bugs list <telepathy-bugs>
Severity: minor    
Priority: high CC: andrunko
Version: git master   
Hardware: Other   
OS: All   
Whiteboard:
i915 platform: i915 features:

Description Olli Salli 2011-10-09 10:44:02 UTC
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
Comment 1 GitLab Migration User 2019-12-03 20:28:36 UTC
-- GitLab Migration Automatic Message --

This bug has been migrated to freedesktop.org's GitLab instance and has been closed from further activity.

You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.freedesktop.org/telepathy/telepathy-qt/issues/27.

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.