docs: Fix many warnings in the docs build

13 files changed, 26 insertions, 63 deletions

diff --git a/docs/reference/ytstenut/Makefile.am b/docs/reference/ytstenut/Makefile.am
index 8f9c788..4c8e8f7 100644
--- a/docs/reference/ytstenut/Makefile.am
+++ b/docs/reference/ytstenut/Makefile.am
@@ -58,6 +58,7 @@ IGNORE_HFILES = \
   yts-client-status.h \
   yts-contact-impl.h \
   yts-contact-internal.h \
+  yts-error.h \
   yts-error-message.h \
   yts-event-message.h \
   yts-factory.h \
diff --git a/docs/reference/ytstenut/ytstenut-docs.xml.in b/docs/reference/ytstenut/ytstenut-docs.xml.in
index 3ff33ae..12345c9 100644
--- a/docs/reference/ytstenut/ytstenut-docs.xml.in
+++ b/docs/reference/ytstenut/ytstenut-docs.xml.in
@@ -37,8 +37,6 @@
     </legalnotice>
   </bookinfo>
 
-  <xi:include href="xml/overview.xml"/>
-
   <part id="yts-reference">
 
     <title>Reference</title>
@@ -46,23 +44,17 @@
     <chapter id="yts-classes">
       <title>Ytstenut Objects</title>
 
-      <xi:include href="xml/yts-capability-status.xml"/>
       <xi:include href="xml/yts-capability.xml"/>
       <xi:include href="xml/yts-client.xml"/>
       <xi:include href="xml/yts-contact.xml"/>
-      <xi:include href="xml/yts-error-message.xml"/>
       <xi:include href="xml/yts-error.xml"/>
-      <xi:include href="xml/yts-event-message.xml"/>
       <xi:include href="xml/yts-file-transfer.xml"/>
       <xi:include href="xml/yts-incoming-file.xml"/>
-      <xi:include href="xml/yts-invocation-message.xml"/>
-      <xi:include href="xml/yts-message.xml"/>
       <xi:include href="xml/yts-metadata-service.xml"/>
       <xi:include href="xml/yts-metadata.xml"/>
       <xi:include href="xml/yts-outgoing-file.xml"/>
       <xi:include href="xml/yts-proxy-service.xml"/>
       <xi:include href="xml/yts-proxy.xml"/>
-      <xi:include href="xml/yts-response-message.xml"/>
       <xi:include href="xml/yts-roster.xml"/>
       <xi:include href="xml/yts-service-adapter.xml"/>
       <xi:include href="xml/yts-service.xml"/>
diff --git a/ytstenut/yts-capability.c b/ytstenut/yts-capability.c
index 4c48175..17b25ab 100644
--- a/ytstenut/yts-capability.c
+++ b/ytstenut/yts-capability.c
@@ -57,7 +57,7 @@ yts_capability_default_init (YtsCapabilityInterface *interface)
  *
  * Get array of supported FQC-IDs.
  *
- * Returns (array zero-terminated=1) (transfer full): Null-terminated array of
+ * Returns: (array zero-terminated=1) (transfer full): Null-terminated array of
  *         FQC-IDs.
  *
  * Since: 0.3
diff --git a/ytstenut/yts-client.c b/ytstenut/yts-client.c
index 0ab614e..502f124 100644
--- a/ytstenut/yts-client.c
+++ b/ytstenut/yts-client.c
@@ -1473,10 +1473,9 @@ yts_client_class_init (YtsClientClass *klass)
    * YtsClient:tp-account:
    *
    * Telepathies #TpAccount object used by this instance.
+   * <note>There is no API guarantee for this and other fields that expose telepathy.</note>
    *
    * Since: 0.4
-   *
-   * <note>There is no API guarantee for this and other fields that expose telepathy.</note>
    */
   pspec = g_param_spec_object ("tp-account", "", "",
                                TP_TYPE_ACCOUNT,
@@ -2723,7 +2722,7 @@ yts_client_emit_error (YtsClient *self, YtsError error)
  * Returns: (transfer none): the jabber id.
  */
 char const *
-yts_client_get_contact_id (const YtsClient *self)
+yts_client_get_contact_id (YtsClient const *self)
 {
   YtsClientPrivate *priv = GET_PRIVATE (self);
 
@@ -2742,7 +2741,7 @@ yts_client_get_contact_id (const YtsClient *self)
  * Returns: (transfer none): the service ID.
  */
 char const *
-yts_client_get_service_id (const YtsClient *self)
+yts_client_get_service_id (YtsClient const *self)
 {
   YtsClientPrivate *priv = GET_PRIVATE (self);
 
diff --git a/ytstenut/yts-contact.c b/ytstenut/yts-contact.c
index badb653..5822705 100644
--- a/ytstenut/yts-contact.c
+++ b/ytstenut/yts-contact.c
@@ -373,7 +373,7 @@ yts_contact_get_name (YtsContact const *self)
  * %NULL. When the #TpContact is available, the YtsContact::notify-tp-contact
  * signal will be emitted.
  *
- * Return value (transfer none): The associated #TpContact.
+ * Returns: (transfer none): The associated #TpContact.
  */
 TpContact *const
 yts_contact_get_tp_contact (YtsContact const *self)
diff --git a/ytstenut/yts-error.c b/ytstenut/yts-error.c
index 9b18cad..718e255 100644
--- a/ytstenut/yts-error.c
+++ b/ytstenut/yts-error.c
@@ -18,20 +18,6 @@
  * Authored by: Tomas Frydrych <tf@linux.intel.com>
  */
 
-/*
- * TODO -- this should probably be rewritten using the GAsync machinery.
- */
-
-/**
- * SECTION:yts-error
- * @short_description: An error object.
- * @title: YtsError
- * @section_id: yts-error
- *
- * #YtsError represents an errror in asynchronous operations. All erros consist
- * of a unique identifier and a status code.
- */
-
 #include "yts-error.h"
 #include "config.h"
 
@@ -41,7 +27,7 @@
  *
  * Retrives error code from #YtsError.
  *
- * Return value: the error code represented by this #YtsError.
+ * Returns: the error code represented by this #YtsError.
  */
 guint
 yts_error_get_code (YtsError error)
@@ -55,7 +41,7 @@ yts_error_get_code (YtsError error)
  *
  * Retrieves the atom identifying the origin of this error from #YtsError.
  *
- * Return value: the atom identifying the operation represented by this
+ * Returns: the atom identifying the operation represented by this
  * #YtsError.
  */
 guint
@@ -76,7 +62,7 @@ yts_error_get_atom (YtsError error)
  * and will have to be shifted left by 16 bits before it can be ored with an
  * error code.
  *
- * Return value: a new atom for use with #YtsError.
+ * Returns: a new atom for use with #YtsError.
  */
 guint32
 yts_error_new_atom ()
diff --git a/ytstenut/yts-message.c b/ytstenut/yts-message.c
index 9ad57db..ca2e6cb 100644
--- a/ytstenut/yts-message.c
+++ b/ytstenut/yts-message.c
@@ -18,13 +18,6 @@
  * Authored by: Tomas Frydrych <tf@linux.intel.com>
  */
 
-/**
- * SECTION:yts-message
- * @short_description: Encapsulates a Ytstenut metadata message.
- *
- * #YtsMessage represents a Ytstenut metadata message.
- */
-
 #include "yts-message.h"
 #include "yts-metadata-internal.h"
 #include "config.h"
@@ -142,7 +135,7 @@ yts_message_finalize (GObject *object)
  *
  * Constructs a new #YtsMessage object, setting the top level attributes.
  *
- * Return value: (transfer full): newly allocated #YtsMessage object.
+ * Returns: (transfer full): newly allocated #YtsMessage object.
  */
 YtsMessage *
 yts_message_new (const char ** attributes)
diff --git a/ytstenut/yts-metadata.c b/ytstenut/yts-metadata.c
index 2e25810..30c10fd 100644
--- a/ytstenut/yts-metadata.c
+++ b/ytstenut/yts-metadata.c
@@ -18,13 +18,6 @@
  * Authored by: Tomas Frydrych <tf@linux.intel.com>
  */
 
-/**
- * SECTION:yts-metadata
- * @short_description: Base class for #YtsMessage.
- *
- * #YtsMetadata is a base class for Ytstenut metadata classes.
- */
-
 #include <string.h>
 #include <rest/rest-xml-parser.h>
 
@@ -248,12 +241,12 @@ yts_metadata_finalize (GObject *object)
  * yts_metadata_get_root_node:
  * @self: #YtsMetadata
  *
- * Returns pointer to the top-level node of the metadata, that can be used
+ * Hands back pointer to the top-level node of the metadata, that can be used
  * with the #RestXmlNode API.
  *
  * NB: Any strings set directly through librest API must be in utf-8 encoding.
  *
- * Return value: (transfer none): #RestXmlNode representing the top-level node
+ * Returns: (transfer none): #RestXmlNode representing the top-level node
  * of the metadata xml.
  */
 RestXmlNode *
@@ -305,7 +298,7 @@ yts_metadata_new_from_xml (const char *xml)
  *
  * Private constructor.
  *
- * Return value: (transfer full): newly allocated #YtsMetadata subclass.
+ * Returns: (transfer full): newly allocated #YtsMetadata subclass.
  */
 YtsMetadata *
 yts_metadata_new_from_node (RestXmlNode       *node,
@@ -343,7 +336,7 @@ yts_metadata_new_from_node (RestXmlNode       *node,
  * node, you need to use yts_metadata_get_root_node() and the librest API to
  * locate and query the appropriate node).
  *
- * Return value: (transfer none): the attribute value or %NULL if attribute
+ * Returns: (transfer none): the attribute value or %NULL if attribute
  * does not exist.
  */
 const char *
@@ -396,7 +389,7 @@ yts_metadata_add_attribute (YtsMetadata *self,
  *
  * Converts the #YtsMetada object in XML representation.
  *
- * Return value: (transfer full): xml string; the caller must free the string
+ * Returns: (transfer full): xml string; the caller must free the string
  * with g_free() when no longer needed.
  */
 char *
@@ -423,7 +416,7 @@ yts_metadata_to_string (YtsMetadata *self)
  * content of any child nodes to xml string. This is intended for use by
  * #YtsClient when sending messages.
  *
- * Return value: (transfer full): top level attributes, the caller holds a
+ * Returns: (transfer full): top level attributes, the caller holds a
  * reference on the returned hash table, which it needs to release with
  * g_hash_table_unref() when no longer needed.
  */
@@ -562,7 +555,7 @@ yts_rest_xml_node_check_children (RestXmlNode *node0, RestXmlNode *node1)
  * NB: equality implies identity of type, i.e., different subclasses will
  * always be unequal.
  *
- * Return value: %TRUE if equal, %FALSE otherwise.
+ * Returns: %TRUE if equal, %FALSE otherwise.
  */
 gboolean
 yts_metadata_is_equal (YtsMetadata *self, YtsMetadata *other)
diff --git a/ytstenut/yts-proxy.c b/ytstenut/yts-proxy.c
index db7fca0..1582834 100644
--- a/ytstenut/yts-proxy.c
+++ b/ytstenut/yts-proxy.c
@@ -222,7 +222,7 @@ yts_proxy_get_fqc_id (YtsProxy *self)
  *
  * Convenience function to create a unique string ID for
  *
- * Returns (transfer full): unique string ID.
+ * Returns: (transfer full): unique string ID.
  *
  * Since: 0.3
  */
@@ -248,7 +248,7 @@ yts_proxy_create_invocation_id (YtsProxy *self)
  * @self: object on which to invoke this method.
  * @invocation_id: a unique identifier for this invocation, this is going to
  *                 be passed back with the response, so it can be mapped.
- * @aspec: name of the method to invoce.
+ * @aspect: name of the method to invoce.
  * @arguments: arguments to pass, this must be an a{sv} that maps to argument
  *             names and types.
  *
diff --git a/ytstenut/yts-proxy.h b/ytstenut/yts-proxy.h
index 594ef19..475b5a6 100644
--- a/ytstenut/yts-proxy.h
+++ b/ytstenut/yts-proxy.h
@@ -47,9 +47,8 @@ typedef struct {
 } YtsProxy;
 
 typedef struct {
-  GObjectClass parent;
-
   /*< private >*/
+  GObjectClass parent;
 
   /* Signals */
 
diff --git a/ytstenut/yts-roster.c b/ytstenut/yts-roster.c
index 510733f..a51ecc5 100644
--- a/ytstenut/yts-roster.c
+++ b/ytstenut/yts-roster.c
@@ -319,7 +319,7 @@ yts_roster_remove_service_by_id (YtsRoster  *self,
  *
  * Finds contact in a roster.
  *
- * Return value: (transfer none): #YtsContact if found, or %NULL.
+ * Returns: (transfer none): #YtsContact if found, or %NULL.
  */
 YtsContact *const
 yts_roster_find_contact_by_id (YtsRoster const  *self,
diff --git a/ytstenut/yts-service.c b/ytstenut/yts-service.c
index 0e52387..4e3da28 100644
--- a/ytstenut/yts-service.c
+++ b/ytstenut/yts-service.c
@@ -305,11 +305,11 @@ yts_service_init (YtsService *self)
 
 /**
  * yts_service_get_id:
- * @service: #YtsService
+ * @self: object on which to invoke this method.
  *
- * Returns the unique id of the the given service.
+ * Gets the unique id of the the given service.
  *
- * Return value: (transfer none): the service-id.
+ * Returns: (transfer none): the service-id.
  */
 char const *
 yts_service_get_id (YtsService *self)
@@ -520,7 +520,7 @@ yts_service_send_dictionary (YtsService         *self,
  *
  * Send @file to remote service @self.
  *
- * Returns (transfer full): an #YtsOutgoingFile instance if the transfer
+ * Returns: (transfer full): an #YtsOutgoingFile instance if the transfer
  * could be initated, or %NULL on error, in which case @error will be set if
  * non-null.
  *
diff --git a/ytstenut/yts-version.h.in b/ytstenut/yts-version.h.in
index 1c563b5..1465858 100644
--- a/ytstenut/yts-version.h.in
+++ b/ytstenut/yts-version.h.in
@@ -54,7 +54,7 @@ G_BEGIN_DECLS
 
 /**
  * YTS_VERSION:
- *s
+ *
  * The full version of the Ytstenut library, like 1.2.3
  */
 #define YTS_VERSION         @PACKAGE_VERSION@