[Bug 36881] Wrong documentation for Tp::Account::connectionStatusChanged (and a bunch of other parts of the API)

[bugzilla-daemon at freedesktop.org]

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

--- Comment #5 from Olli Salli <ollisal at gmail.com> 2011-06-01 06:52:46 PDT ---
- * \brief The AbstractClient class represents a Telepathy client.
+ * \brief The AbstractClient class represents a \telepathy client.

- * \brief The AbstractClientObserver class represents a Telepathy observer.
+ * \brief The AbstractClientObserver class represents a \telepathy observer.

- * \brief The AbstractClientApprover class represents a Telepathy approver.
+ * \brief The AbstractClientApprover class represents a \telepathy approver.

- * \brief The AbstractClientHandler class represents a Telepathy handler.
+ * \brief The AbstractClientHandler class represents a \telepathy handler.

- * \brief The AccountManager class represents a Telepathy account manager.
+ * \brief The AccountManager class represents a \telepathy account manager.

... etc

I think these links are completely confusing. Imagine one using a client
library to access Telepathy, and examining the docs for implementing e.g. a
Handler. Why would they specifically there want to be directed to the Telepathy
project front page? IMO we should only have a link to the Tp project front page
from the documentation front page / overview description of the entire library.

Something that is actually be useful would be to link "Telepathy Client" ->
spec for Client, "Telepathy Observer" -> spec for Client.Observer etc.

To rephrase, when reading documentation for a specific part of the TpQt4 API,
you don't suddenly get an urge to go and find out what the Telepathy project is
all about; but you might want to know about this specific thing in the Tp spec,
or D-Bus documentation, etc.

+ * Telepathy-Qt4 uses \dbus to communicate with applications implementing the
\telepathy_spec.

This is fine though, because it's in an overview section where one is likely to
want to go to project overviews from.

I realize you probably just searched and replaced all occurrences of the word
Telepathy in the docs by a link to the telepathy front page, and would rather
not spend time linking to the actually relevant specific parts of the Telepathy
spec instead. This is fine; the branch is mergeable as long as you revert your
change to link to the Telepathy project front page from 84 API specific
sections, and only keep the links in overviews, and the spec links. One just
doesn't want to be directed 84 times to an overview of an open-source project!

Otherwise the latest changes, and the branch as a whole, look fine.

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