docs: many misc fixupsmisc

We still have multiple gtk-doc warnings which are much harder to fix,
such as things like this in the spec:

    "see bug #26417"

html/telepathy-glib-channel-text.html:1538: warning: no link for: '26417:CAPS' -> (<span class="type">26417</span>).

and the change I made to the code generator in c0b13f7ccc26e78.

Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>

11 files changed, 34 insertions, 31 deletions

diff --git a/telepathy-glib/account.c b/telepathy-glib/account.c
index c56359ad2..a871b8e73 100644
--- a/telepathy-glib/account.c
+++ b/telepathy-glib/account.c
@@ -1367,7 +1367,7 @@ tp_account_class_init (TpAccountClass *klass)
    * <ulink url="http://telepathy.freedesktop.org/spec/">the Telepathy D-Bus
    * Interface Specification</ulink>. They will typically include
    * <literal>debug-message</literal>, which is a debugging message in the C
-   * locale, analogous to #GError.message.
+   * locale, analogous to #GError<!-- -->.message.
    *
    * One can receive change notifications on this property by connecting
    * to the #TpAccount::status-changed signal, or by connecting
@@ -1390,10 +1390,10 @@ tp_account_class_init (TpAccountClass *klass)
   /**
    * TpAccount:connection:
    *
-   * The connection of the account, or NULL if account is offline.
+   * The connection of the account, or %NULL if account is offline.
    * Note that the returned #TpConnection is not guaranteed to have any
    * features pre-prepared (not even %TP_CONNECTION_FEATURE_CORE) unless
-   * %TP_ACCOUNT_FEATURE_ACCOUNT has been prepared on the account
+   * %TP_ACCOUNT_FEATURE_CONNECTION has been prepared on the account
    *
    * One can receive change notifications on this property by connecting
    * to the #GObject::notify signal and using this property as the signal
diff --git a/telepathy-glib/base-connection.c b/telepathy-glib/base-connection.c
index 49299d09a..498104819 100644
--- a/telepathy-glib/base-connection.c
+++ b/telepathy-glib/base-connection.c
@@ -1355,9 +1355,9 @@ tp_base_connection_constructor (GType type, guint n_construct_properties,
  * #TpBaseConnection::clients-interested and
  * #TpBaseConnection::clients-uninterested.
  *
- * This method must be called from the #GObjectClass.constructed or
- * #GObjectClass.constructor callback (otherwise, it will run too late to be
- * useful).
+ * This method must be called from the #GObjectClass<!--
+ * -->.constructed or #GObjectClass<!-- -->.constructor callback
+ * (otherwise, it will run too late to be useful).
  */
 void
 tp_base_connection_add_possible_client_interest (TpBaseConnection *self,
@@ -1573,8 +1573,9 @@ tp_base_connection_class_init (TpBaseConnectionClass *klass)
    * TpBaseConnection:dbus-status: (skip)
    *
    * The Connection.Status as visible on D-Bus, which is the same as
-   * #TpBaseConnection.status except that %TP_INTERNAL_CONNECTION_STATUS_NEW
-   * is replaced by %TP_CONNECTION_STATUS_DISCONNECTED.
+   * #TpBaseConnection<!-- -->.status except that
+   * %TP_INTERNAL_CONNECTION_STATUS_NEW is replaced by
+   * %TP_CONNECTION_STATUS_DISCONNECTED.
    *
    * The #GObject::notify signal is not currently emitted for this property.
    *
@@ -2708,7 +2709,7 @@ void tp_base_connection_finish_shutdown (TpBaseConnection *self)
  * @reason: The reason code to use in the StatusChanged signal
  *          (a less specific, non-extensible version of @error_name)
  *
- * Changes the #TpBaseConnection.status of @self to
+ * Changes the #TpBaseConnection<!-- -->.status of @self to
  * %TP_CONNECTION_STATUS_DISCONNECTED, as if by a call to
  * tp_base_connection_change_status(), but additionally emits the
  * <code>ConnectionError</code> D-Bus signal to provide more details about the
@@ -2787,7 +2788,7 @@ tp_base_connection_disconnect_with_dbus_error (TpBaseConnection *self,
  * Any other valid transition does the following, in this order:
  *
  * <itemizedlist>
- * <listitem>Update #TpBaseConnection.status;</listitem>
+ * <listitem>Update #TpBaseConnection<!-- -->.status;</listitem>
  * <listitem>If the new state is #TP_CONNECTION_STATUS_DISCONNECTED, call
  *    tp_channel_factory_iface_close_all() on all channel factories</listitem>
  * <listitem>Emit the D-Bus StatusChanged signal;</listitem>
diff --git a/telepathy-glib/base-password-channel.c b/telepathy-glib/base-password-channel.c
index c85eda83d..583d40329 100644
--- a/telepathy-glib/base-password-channel.c
+++ b/telepathy-glib/base-password-channel.c
@@ -23,14 +23,16 @@
  * @short_description: a simple X-TELEPATHY-PASSWORD channel
  *
  * This class implements a SASL Authentication channel with the
- * X-TELEPATHY-PASSWORD SASL mechanism.  Most of the time, you should not use
- * or instantiate this class directly.  It is used by #TpBasePasswordManager
- * behind the scenes.  In some special circumstances (e.g. when the authentication
- * channel needs to implement additional interfaces), it may be necessary to
- * create your own custom authentication channels instead of letting
- * #TpBasePasswordManager create them automatically.  In this case, you
- * should derive your channel from this class and then pass the channel as an
- * argument to tp_simple_password_manager_prompt_for_channel_async().
+ * X-TELEPATHY-PASSWORD SASL mechanism.  Most of the time, you should
+ * not use or instantiate this class directly.  It is used by
+ * #TpSimplePasswordManager behind the scenes.  In some special
+ * circumstances (e.g. when the authentication channel needs to
+ * implement additional interfaces), it may be necessary to create
+ * your own custom authentication channels instead of letting
+ * #TpSimplePasswordManager create them automatically.  In this case,
+ * you should derive your channel from this class and then pass the
+ * channel as an argument to
+ * tp_simple_password_manager_prompt_for_channel_async().
  *
  * Since: 0.13.15
  */
diff --git a/telepathy-glib/base-room-config.c b/telepathy-glib/base-room-config.c
index 56d627acd..078197640 100644
--- a/telepathy-glib/base-room-config.c
+++ b/telepathy-glib/base-room-config.c
@@ -1030,7 +1030,7 @@ tp_base_room_config_iface_init (
  *
  * Returns the channel to which @self is attached.
  *
- * Returns: (transfer full): the #TpBaseChannel:channel property.
+ * Returns: (transfer full): the #TpBaseRoomConfig:channel property.
  */
 TpBaseChannel *
 tp_base_room_config_dup_channel (
diff --git a/telepathy-glib/channel.c b/telepathy-glib/channel.c
index b407bfd23..73bf696b3 100644
--- a/telepathy-glib/channel.c
+++ b/telepathy-glib/channel.c
@@ -299,7 +299,7 @@ tp_channel_get_channel_type_id (TpChannel *self)
  * guaranteed to have its final value until the %TP_CHANNEL_FEATURE_CORE
  * feature is ready.
  *
- * If %handle_type is not %NULL, the type of handle is written into it.
+ * If @handle_type is not %NULL, the type of handle is written into it.
  * This will be %TP_UNKNOWN_HANDLE_TYPE if the handle has not yet been
  * discovered, or %TP_HANDLE_TYPE_NONE if there is no handle with which this
  * channel will always communicate. This is the same as the
diff --git a/telepathy-glib/connection-contact-list.c b/telepathy-glib/connection-contact-list.c
index 01988a9a7..862c04e89 100644
--- a/telepathy-glib/connection-contact-list.c
+++ b/telepathy-glib/connection-contact-list.c
@@ -1167,7 +1167,7 @@ tp_connection_get_contact_groups (TpConnection *self)
  * remove all other members.
  *
  * For this to work properly @self must have interface
- * %TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUP.
+ * %TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS.
  *
  * Since: 0.15.5
  */
@@ -1215,7 +1215,7 @@ tp_connection_set_group_members_finish (TpConnection *self,
  * Add the given @contacts to the given @group, creating it if necessary.
  *
  * For this to work properly @self must have interface
- * %TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUP.
+ * %TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS.
  *
  * Since: 0.15.5
  */
@@ -1264,7 +1264,7 @@ tp_connection_add_to_group_finish (TpConnection *self,
  * left in the group afterwards, the group MAY itself be removed.
  *
  * For this to work properly @self must have interface
- * %TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUP.
+ * %TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS.
  *
  * Since: 0.15.5
  */
@@ -1309,7 +1309,7 @@ tp_connection_remove_from_group_finish (TpConnection *self,
  * Remove all members from the given group, then remove the group itself.
  *
  * For this to work properly @self must have interface
- * %TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUP.
+ * %TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS.
  *
  * Since: 0.15.5
  */
@@ -1366,7 +1366,7 @@ tp_connection_remove_group_finish (TpConnection *self,
  * the old group.
  *
  * For this to work properly @self must have interface
- * %TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUP.
+ * %TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS.
  *
  * Since: 0.15.5
  */
diff --git a/telepathy-glib/contact.c b/telepathy-glib/contact.c
index 6f9da3f32..6c8127984 100644
--- a/telepathy-glib/contact.c
+++ b/telepathy-glib/contact.c
@@ -110,7 +110,7 @@ struct _TpContact {
  *  interface. (available since 0.13.12)
  * @TP_CONTACT_FEATURE_CONTACT_GROUPS: #TpContact:contact-groups
  *  (available since 0.13.14)
- * @TP_CONTACT_FEATURE_CONTACT_BLOCKING: #TpContact:is-blocking. Require
+ * @TP_CONTACT_FEATURE_CONTACT_BLOCKING: #TpContact:is-blocked. Require
  *  Connection implementing the %TP_IFACE_CONNECTION_INTERFACE_CONTACT_BLOCKING
  *  interface. (available since 0.17.0)
  *
@@ -719,7 +719,7 @@ set_contact_groups_cb (TpConnection *connection,
  * If the operation is successful and %TP_CONTACT_FEATURE_CONTACT_GROUPS is
  * prepared, the #TpContact:contact-groups property will be
  * updated (emitting "notify::contact-groups" signal) and
- * #TpContact:contact-groups-changed signal will be emitted before @callback
+ * #TpContact::contact-groups-changed signal will be emitted before @callback
  * is called. That means you can call tp_contact_get_contact_groups() to get the
  * new contact groups inside @callback.
  *
diff --git a/telepathy-glib/file-transfer-channel.c b/telepathy-glib/file-transfer-channel.c
index a377c86f4..e306f79b7 100644
--- a/telepathy-glib/file-transfer-channel.c
+++ b/telepathy-glib/file-transfer-channel.c
@@ -822,7 +822,7 @@ tp_file_transfer_channel_class_init (TpFileTransferChannelClass *klass)
     *
     * For outgoing file transfers, this property is a #GFile for the
     * location of the file being sent (given by
-    * tp_file_transfer_provide_file_async()). The feature
+    * tp_file_transfer_channel_provide_file_async()). The feature
     * %TP_FILE_TRANSFER_CHANNEL_FEATURE_CORE does not have to be
     * prepared and there is no change notification.
     *
diff --git a/telepathy-glib/proxy-methods.c b/telepathy-glib/proxy-methods.c
index 7711b5873..20c35252d 100644
--- a/telepathy-glib/proxy-methods.c
+++ b/telepathy-glib/proxy-methods.c
@@ -386,7 +386,7 @@ tp_proxy_pending_call_free (TpProxyPendingCall *pc)
 
 /**
  * tp_proxy_pending_call_v0_completed:
- * @p: a #TpProxyPendingCall allocated with tp_proxy_pending_call_new_v0()
+ * @p: a #TpProxyPendingCall allocated with tp_proxy_pending_call_v0_new()
  *
  * Indicate that dbus-glib has finished with this pending call, and therefore
  * either tp_proxy_pending_call_v0_take_results() has already been called,
diff --git a/telepathy-glib/text-mixin.c b/telepathy-glib/text-mixin.c
index b93b76f4c..2af5e286f 100644
--- a/telepathy-glib/text-mixin.c
+++ b/telepathy-glib/text-mixin.c
@@ -203,7 +203,7 @@ tp_text_mixin_init (GObject *obj,
  * tp_text_mixin_set_message_types:
  * @obj: An object with this mixin
  * @...: guints representing members of #TpChannelTextMessageType, terminated
- *  by %G_MAXUINT
+ *  by G_MAXUINT
  *
  * Set the supported message types.
  */
diff --git a/telepathy-glib/util.c b/telepathy-glib/util.c
index 317533ccc..69b53c501 100644
--- a/telepathy-glib/util.c
+++ b/telepathy-glib/util.c
@@ -1629,7 +1629,7 @@ _tp_create_channel_request_list (TpSimpleClientFactory *factory,
  * character (U+FFFD).
  *
  * This method is a verbatim copy of glib's internal
- * _g_utf8_make_valid() function, and will be deprecated as
+ * _g_utf8_make_valid<!-- -->() function, and will be deprecated as
  * soon as the glib one becomes public.
  *
  * Returns: a new valid UTF8 string