[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 #6 from Olli Salli <ollisal at gmail.com> 2011-06-01 07:37:05 PDT ---
I noticed from the links to the spec that some of the doc comments in which
they are contained are incorrect:

/**
 * Return a map containing extensible error details related to
 * connectionError().
 *
 * The keys for this map are defined by the \telepathy_spec.
 * They will typically include <literal>debug-message</literal>, which is a
debugging
 * message in the C locale.
 *
 * Note that this method may return a different value from the one returned by
 * Connection::errorDetails() on this account connection.
 * See connectionStatus() for more details.
 *
 * This method requires Account::FeatureCore to be enabled.
 *
 * \return A map containing extensible error details related to
 *         connectionError().
 * \sa connectionError(), connectionStatus(), connectionStatusReason(),
connectionStatusChanged(),
 *     Connection::ErrorDetails.
 */
Connection::ErrorDetails Account::connectionErrorDetails() const

It doesn't return a map with some well-known keys, it returns a higher-level
ErrorDetails object.

- * \brief The ProtocolInfo class represents a Telepathy protocol information.
+ * \brief The ProtocolInfo class represents a \telepathy protocol information.

Still a link to the overview from specific API, and has grammatical issues.
Rather, say "represents a Telepathy Protocol". Bonus points for linking to 
http://telepathy.freedesktop.org/spec/Protocol.html.

+ * \brief A class representing a Telepathy abstract tube.

There's no such thing as a Telepathy abstract tube. Perhaps "This is the base
class for all tube types"?

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