[Bug 41626] New: Lots of doxygen warnings while generating documentation (Junior job!)

[bugzilla-daemon at freedesktop.org]

https://bugs.freedesktop.org/show_bug.cgi?id=41626

           Summary: Lots of doxygen warnings while generating
                    documentation (Junior job!)
           Product: Telepathy
           Version: git master
          Platform: Other
        OS/Version: All
            Status: NEW
          Severity: minor
          Priority: high
         Component: tp-qt4
        AssignedTo: telepathy-bugs at lists.freedesktop.org
        ReportedBy: ollisal at gmail.com
         QAContact: telepathy-bugs at lists.freedesktop.org
                CC: andrunko at gmail.com


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

-- 
Configure bugmail: https://bugs.freedesktop.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug.
You are the assignee for the bug.