[gtk+] Add documentation for content (de)serializers

[Matthias Clasen <matthiasc src gnome org>]

commit 6374226d6b2f49f88a3e526c03f9b0f968043dd8
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Dec 26 14:04:12 2017 -0500

    Add documentation for content (de)serializers

 gdk/gdkcontentdeserializer.c |   62 +++++++++++++++++++++++++++++++++++++++---
 gdk/gdkcontentdeserializer.h |   14 +++++++++
 gdk/gdkcontentserializer.c   |   59 +++++++++++++++++++++++++++++++++++++++
 gdk/gdkcontentserializer.h   |   14 +++++++++
 4 files changed, 145 insertions(+), 4 deletions(-)
---
diff --git a/gdk/gdkcontentdeserializer.c b/gdk/gdkcontentdeserializer.c
index 91c5d6e..627308a 100644
--- a/gdk/gdkcontentdeserializer.c
+++ b/gdk/gdkcontentdeserializer.c
@@ -30,11 +30,11 @@
 /**
  * SECTION:gdkcontentdeserializer
  * @Short_description: Deserialize content for transfer
- * @Title: GdkContentSerializer
- * @See_also: #GdkContentDeserializer
+ * @Title: GdkContentDeserializer
+ * @See_also: #GdkContentSerializer
  *
- * A GdkContentDeserializer is used to deserialize content for inter-application
- * data transfers.
+ * A GdkContentDeserializer is used to deserialize content received via
+ * inter-application data transfers.
  */
 
 typedef struct _Deserializer Deserializer;
@@ -366,6 +366,17 @@ gdk_content_deserializer_return_error (GdkContentDeserializer *deserializer,
   gdk_content_deserializer_return_success (deserializer);
 }
 
+/**
+ * gdk_content_register_deserializer:
+ * @mime_type: the mime type which the function can deserialize from
+ * @type: the type of objects that the function creates
+ * @deserialize: the callback
+ * @data: data that @deserialize can access
+ * @notify: destroy notify for @data
+ *
+ * Registers a function to create objects of a given @type from
+ * a serialized representation with the given mime type.
+ */
 void
 gdk_content_register_deserializer (const char                *mime_type,
                                    GType                      type,
@@ -415,6 +426,15 @@ lookup_deserializer (const char *mime_type,
   return NULL;
 }
 
+/**
+ * gdk_content_formats_union_deserialize_gtypes:
+ * @formats: a #GdkContentFormats
+ *
+ * Add GTypes for mime types in @formats for which deserializers are
+ * registered.
+ *
+ * Return: a new #GdkContentFormats
+ */
 GdkContentFormats *
 gdk_content_formats_union_deserialize_gtypes (GdkContentFormats *formats)
 {
@@ -441,6 +461,15 @@ gdk_content_formats_union_deserialize_gtypes (GdkContentFormats *formats)
   return gdk_content_formats_builder_free (builder);
 }
 
+/**
+ * gdk_content_formats_union_deserialize_mime_types:
+ * @formats: a #GdkContentFormats
+ *
+ * Add mime types for GTypes in @formats for which deserializers are
+ * registered.
+ *
+ * Return: a new #GdkContentFormats
+ */
 GdkContentFormats *
 gdk_content_formats_union_deserialize_mime_types (GdkContentFormats *formats)
 {
@@ -478,6 +507,20 @@ deserialize_not_found (GdkContentDeserializer *deserializer)
   gdk_content_deserializer_return_error (deserializer, error);
 }
 
+/**
+ * gdk_content_deserialize_async:
+ * @stream: a #GInputStream to read the serialized content from
+ * @mime_type: the mime type to deserialize from
+ * @type: the GType to deserialize from
+ * @io_priority: the io priority of the operation
+ * @cancellable: (nullable): optional #GCancellable object
+ * @callback: (scope async): callback to call when the operation is done
+ * @user_data: (closure): data to pass to the callback function
+ *
+ * Read content from the given input stream and deserialize it, asynchronously.
+ * When the operation is finished, @callback will be called. You can then
+ * call gdk_content_deserialize_finish() to get the result of the operation.
+ */
 void
 gdk_content_deserialize_async (GInputStream        *stream,
                                const char          *mime_type,
@@ -506,6 +549,17 @@ gdk_content_deserialize_async (GInputStream        *stream,
                                 user_data);
 }
 
+/**
+ * gdk_content_deserialize_finish:
+ * @result: the #GAsyncResult
+ * @value: return location for the result of the operation
+ * @error: return location for an error
+ *
+ * Finishes a content deserialization operation.
+ *
+ * Returns: %TRUE if the operation was successful. In this case, @value is set.
+ *          %FALSE if an error occurred. In this case, @error is set
+ */
 gboolean
 gdk_content_deserialize_finish (GAsyncResult  *result,
                                 GValue        *value,
diff --git a/gdk/gdkcontentdeserializer.h b/gdk/gdkcontentdeserializer.h
index b08d498..d0fc4cc 100644
--- a/gdk/gdkcontentdeserializer.h
+++ b/gdk/gdkcontentdeserializer.h
@@ -32,8 +32,22 @@ G_BEGIN_DECLS
 #define GDK_CONTENT_DESERIALIZER(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), 
GDK_TYPE_CONTENT_DESERIALIZER, GdkContentDeserializer))
 #define GDK_IS_CONTENT_DESERIALIZER(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), 
GDK_TYPE_CONTENT_DESERIALIZER))
 
+/**
+ * GdkContentDeserializer:
+ *
+ * Should not be accessed directly.
+ */
 typedef struct _GdkContentDeserializer GdkContentDeserializer;
 
+/**
+ * GdkContentDeserializeFunc:
+ * @deserializer: a #GdkContentDeserializer
+ *
+ * The type of a function that can be registered with gdk_content_register_deserializer().
+ * When the function gets called to operate on content, it can call functions on the
+ * @deserializer object to obtain the mime type, input stream, user data, etc. for its
+ * operation.
+ */
 typedef void (* GdkContentDeserializeFunc) (GdkContentDeserializer *deserializer);
 
 GDK_AVAILABLE_IN_3_94
diff --git a/gdk/gdkcontentserializer.c b/gdk/gdkcontentserializer.c
index f92789b..ff22678 100644
--- a/gdk/gdkcontentserializer.c
+++ b/gdk/gdkcontentserializer.c
@@ -39,6 +39,12 @@
  * data transfers.
  */
 
+/**
+ * GdkContentSerializer:
+ *
+ * Contains only private fields and should not be directly accessed.
+ */
+
 typedef struct _Serializer Serializer;
 
 struct _Serializer 
@@ -369,6 +375,17 @@ gdk_content_serializer_return_error (GdkContentSerializer *serializer,
   gdk_content_serializer_return_success (serializer);
 }
 
+/**
+ * gdk_content_register_serializer:
+ * @type: the type of objects that the function can serialize
+ * @mime_type: the mime type to serialize to
+ * @serialize: the callback
+ * @data: data that @serialize can access
+ * @notify: destroy notify for @data
+ *
+ * Registers a function to convert objects of the given @type to
+ * a serialized representation with the given mime type.
+ */
 void
 gdk_content_register_serializer (GType                    type,
                                  const char              *mime_type,
@@ -418,6 +435,15 @@ lookup_serializer (const char *mime_type,
   return NULL;
 }
 
+/**
+ * gdk_content_formats_union_serialize_gtypes:
+ * @formats: a #GdkContentFormats
+ *
+ * Add GTypes for the mime types in @formats for which serializers are
+ * registered.
+ *
+ * Return: a new #GdkContentFormats
+ */
 GdkContentFormats *
 gdk_content_formats_union_serialize_gtypes (GdkContentFormats *formats)
 {
@@ -444,6 +470,15 @@ gdk_content_formats_union_serialize_gtypes (GdkContentFormats *formats)
   return gdk_content_formats_builder_free (builder);
 }
 
+/**
+ * gdk_content_formats_union_serialize_mime_types:
+ * @formats: a #GdkContentFormats
+ *
+ * Add mime types for GTypes in @formats for which serializers are
+ * registered.
+ *
+ * Return: a new #GdkContentFormats
+ */
 GdkContentFormats *
 gdk_content_formats_union_serialize_mime_types (GdkContentFormats *formats)
 {
@@ -481,6 +516,20 @@ serialize_not_found (GdkContentSerializer *serializer)
   gdk_content_serializer_return_error (serializer, error);
 }
 
+/**
+ * gdk_content_serialize_async:
+ * @stream: a #GOutputStream to write the serialized content to
+ * @mime_type: the mime type to serialize to
+ * @value: the content to serialize
+ * @io_priority: the io priority of the operation
+ * @cancellable: (nullable): optional #GCancellable object
+ * @callback: (scope async): callback to call when the operation is done
+ * @user_data: (closure): data to pass to the callback function
+ *
+ * Serialize content and write it to the given output stream, asynchronously.
+ * When the operation is finished, @callback will be called. You can then
+ * call gdk_content_serialize_finish() to get the result of the operation.
+ */
 void
 gdk_content_serialize_async (GOutputStream       *stream,
                              const char          *mime_type,
@@ -509,6 +558,16 @@ gdk_content_serialize_async (GOutputStream       *stream,
                               user_data);
 }
 
+/**
+ * gdk_content_serialize_finish:
+ * @result: the #GAsyncResult
+ * @error: return location for an error
+ *
+ * Finishes a content serialization operation.
+ *
+ * Returns: %TRUE if the operation was successful, %FALSE if an
+ *   error occurred. In this case, @error is set
+ */
 gboolean
 gdk_content_serialize_finish (GAsyncResult  *result,
                               GError       **error)
diff --git a/gdk/gdkcontentserializer.h b/gdk/gdkcontentserializer.h
index 8b6dcf7..b2c34d4 100644
--- a/gdk/gdkcontentserializer.h
+++ b/gdk/gdkcontentserializer.h
@@ -32,8 +32,22 @@ G_BEGIN_DECLS
 #define GDK_CONTENT_SERIALIZER(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), GDK_TYPE_CONTENT_SERIALIZER, 
GdkContentSerializer))
 #define GDK_IS_CONTENT_SERIALIZER(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDK_TYPE_CONTENT_SERIALIZER))
 
+/**
+ * GdkContentSerializer:
+ *
+ * Should not be accessed directly.
+ */
 typedef struct _GdkContentSerializer GdkContentSerializer;
 
+/**
+ * GdkContentSerializeFunc:
+ * @serializer: a #GdkContentSerializer
+ *
+ * The type of a function that can be registered with gdk_content_register_serializer().
+ * When the function gets called to operate on content, it can call functions on the
+ * @serializer object to obtain the mime type, output stream, user data, etc. for its
+ * operation.
+ */
 typedef void (* GdkContentSerializeFunc) (GdkContentSerializer *serializer);
 
 GDK_AVAILABLE_IN_3_94