[gtk+/wip/clipboard] GdkClipboard: Add docs

[Matthias Clasen <matthiasc src gnome org>]

commit cc5d0d610bb45ea973afc5cf4490ff55a884610a
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Jun 16 09:10:16 2014 -0400

    GdkClipboard: Add docs
    
    Add a first round of doc comments.

 gdk/gdkclipboard.c |  298 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 gdk/gdkdisplay.c   |   25 +++++
 2 files changed, 323 insertions(+), 0 deletions(-)
---
diff --git a/gdk/gdkclipboard.c b/gdk/gdkclipboard.c
index 4f25447..9a52e20 100644
--- a/gdk/gdkclipboard.c
+++ b/gdk/gdkclipboard.c
@@ -19,6 +19,42 @@
 #include <gdk/gdkclipboardprivate.h>
 
 
+/**
+ * SECTION:gdkclipboard
+ * @Short_description: A clipboard class
+ * @Title: GdkClipboard
+ *
+ * The #GdkClipboard object represent a clipboard of data that
+ * is shared between different processes or between different widgets
+ * in the same process. GDK backends are responsible for implementing
+ * the #GdkClipboard API using their platforms data exchange mechanisms.
+ *
+ * GDK supports two different clipboards, which are historically named
+ * CLIPBOARD and PRIMARY. To obtain these clipboards, use
+ * gdk_display_get_clipboard() and gdk_display_get_primary(). The
+ * CLIPBOARD is supposed to be controlled explicitly by the user (e.g.
+ * using the common Ctrl-X/Ctrl-V shortcuts). The PRIMARY clipboard
+ * is supposed to always correspond to 'the current selection', which
+ * is a somewhat fuzzy concept.  On platforms that don't support this
+ * distinction, GDK will provide a fallback implementation for the
+ * PRIMARY clipboard that only allows local data exchange inside the
+ * application.
+ *
+ * A GdkClipboard can hold data in different formats and types. Content
+ * types are represented as strings with mime types, such as "application/pdf".
+ *
+ * The most important data types, text and images, are supported explicitly
+ * with the functions gdk_clipboard_set_text(), gdk_clipboard_get_text_async(),
+ * gdk_clipboard_text_available() for text and gdk_clipboard_set_image(),
+ * gdk_clipboard_get_image_async() and gdk_clipboard_image_available()
+ * for images.
+ *
+ * To store other content in a GdkClipboard, use gdk_clipboard_set_bytes()
+ * or gdk_clipboard_set_data() and their corresponding getter functions.
+ *
+ * GdkClipboard was introduced in GTK+ 3.14.
+ */
+
 typedef struct _GdkClipboardPrivate GdkClipboardPrivate;
 
 struct _GdkClipboardPrivate
@@ -92,6 +128,22 @@ _gdk_clipboard_get_available_content (GdkClipboard *clipboard)
   return priv->content;
 }
 
+/**
+ * gdk_clipboard_get_content_types:
+ * @clipboard: a #GdkClipboard
+ *
+ * Gets the content types for which the clipboard can currently
+ * provide content.
+ *
+ * Note that text and image data is not represented by content types.
+ * Instead, use gdk_clipboard_text_available() and
+ * gdk_clipboard_image_available() to check for text or image
+ * content.
+ *
+ * Returns: (transfer none): Content type of the current content
+ *
+ * Since: 3.14
+ */
 const gchar **
 gdk_clipboard_get_content_types (GdkClipboard *clipboard)
 {
@@ -118,6 +170,23 @@ strv_contains (const gchar **strv, const gchar *s)
   return FALSE;
 }
 
+/**
+ * gdk_clipboard_data_available:
+ * @clipboard: a #GdkClipboard
+ * @content_type: the content type to check for
+ *
+ * Returns whether the clipboard can currently provide content
+ * of the given type.
+ *
+ * Note that text and image data is not represented by content types.
+ * Instead, use gdk_clipboard_text_available() and
+ * gdk_clipboard_image_available() to check for text or image
+ * content.
+ *
+ * Returns: (transfer none): %TRUE if content of the given type is available
+ *
+ * Since: 3.14
+ */
 gboolean
 gdk_clipboard_data_available (GdkClipboard *clipboard,
                               const gchar  *content_type)
@@ -132,6 +201,23 @@ gdk_clipboard_data_available (GdkClipboard *clipboard,
          strv_contains ((const gchar **)priv->content_types, content_type);
 }
 
+/**
+ * gdk_clipboard_get_text_async:
+ * @clipboard: a #GdkClipboard
+ * @cancellable: (allow-none): a #GCancellable
+ * @callback: the callback to call when the text is available
+ * @user_data: data that gets passed to @callback
+ *
+ * Retrieves the text content of the clipboard. This may involve
+ * inter-process communication with the current owner of the system
+ * clipboard. Therefore, it is implemented as an asynchronous
+ * operation. 
+ *
+ * When the asynchronous operation is completed, @callback is called.
+ * It should call gdk_clipboard_get_text_finish() to retrieve the text.
+ *
+ * Since: 3.14
+ */
 void
 gdk_clipboard_get_text_async (GdkClipboard        *clipboard,
                               GCancellable        *cancellable,
@@ -143,6 +229,22 @@ gdk_clipboard_get_text_async (GdkClipboard        *clipboard,
   GDK_CLIPBOARD_GET_CLASS (clipboard)->get_text_async (clipboard, cancellable, callback, user_data);
 }
 
+/**
+ * gdk_clipboard_get_text_finish:
+ * @clipboard: a #GdkClipboard
+ * @res: the #GAsyncResult
+ * @error: return location for an error
+ *
+ * Obtains the result of a gdk_clipboard_get_text_async() call.
+ * This function may only be called from a callback passed
+ * to gdk_clipboard_get_text_async().
+ *
+ * If the clipboard does not contain text, %NULL is returned.
+ *
+ * Returns: (transfer full): the current text content of the clipboard
+ *
+ * Since: 3.14
+ */
 gchar *
 gdk_clipboard_get_text_finish (GdkClipboard  *clipboard,
                                GAsyncResult  *res,
@@ -153,6 +255,20 @@ gdk_clipboard_get_text_finish (GdkClipboard  *clipboard,
   return GDK_CLIPBOARD_GET_CLASS (clipboard)->get_text_finish (clipboard, res, error);
 }
 
+/**
+ * gdk_clipboard_set_text:
+ * @clipboard: a #GdkClipboard
+ * @text: the text to store in the clipboard
+ *
+ * Sets the clipboard content to the given text.
+ *
+ * The clipboard makes a copy of the text and provides it
+ * to requestors until the clipboard gets overwritten with
+ * new content from this or another process, or until
+ * gdk_clipboard_clear() is called.
+ *
+ * Since: 3.14
+ */
 void
 gdk_clipboard_set_text (GdkClipboard *clipboard,
                         const gchar  *text)
@@ -162,6 +278,16 @@ gdk_clipboard_set_text (GdkClipboard *clipboard,
   GDK_CLIPBOARD_GET_CLASS (clipboard)->set_text (clipboard, text);
 }
 
+/**
+ * gdk_clipboard_text_available:
+ * @clipboard:
+ *
+ * Returns whether the clipboard currently contains text.
+ *
+ * Returns: %TRUE if the clipboard contains text
+ *
+ * Since: 3.14
+ */
 gboolean
 gdk_clipboard_text_available (GdkClipboard *clipboard)
 {
@@ -174,6 +300,23 @@ gdk_clipboard_text_available (GdkClipboard *clipboard)
   return ((priv->content & TEXT_CONTENT) != 0);
 }
 
+/**
+ * gdk_clipboard_get_image_async:
+ * @clipboard: a #GdkClipboard
+ * @cancellable: (allow-none): a #GCancellable
+ * @callback: the callback to call when the text is available
+ * @user_data: data that gets passed to @callback
+ *
+ * Retrieves the image content of the clipboard. This may involve
+ * inter-process communication with the current owner of the system
+ * clipboard. Therefore, it is implemented as an asynchronous
+ * operation. 
+ *
+ * When the asynchronous operation is completed, @callback is called.
+ * It should call gdk_clipboard_get_image_finish() to retrieve the text.
+ *
+ * Since: 3.14
+ */
 void
 gdk_clipboard_get_image_async (GdkClipboard        *clipboard,
                                GCancellable        *cancellable,
@@ -185,6 +328,22 @@ gdk_clipboard_get_image_async (GdkClipboard        *clipboard,
   GDK_CLIPBOARD_GET_CLASS (clipboard)->get_image_async (clipboard, cancellable, callback, user_data);
 }
 
+/**
+ * gdk_clipboard_get_image_finish:
+ * @clipboard: a #GdkClipboard
+ * @res: the #GAsyncResult
+ * @error: return location for an error
+ *
+ * Obtains the result of a gdk_clipboard_get_image_async() call.
+ * This function may only be called from a callback passed
+ * to gdk_clipboard_get_image_async().
+ *
+ * If the clipboard does not contain an image, %NULL is returned.
+ *
+ * Returns: (transfer full): the current image content of the clipboard
+ *
+ * Since: 3.14
+ */
 GdkPixbuf *
 gdk_clipboard_get_image_finish (GdkClipboard  *clipboard,
                                 GAsyncResult  *res,
@@ -195,6 +354,20 @@ gdk_clipboard_get_image_finish (GdkClipboard  *clipboard,
   return GDK_CLIPBOARD_GET_CLASS (clipboard)->get_image_finish (clipboard, res, error);
 }
 
+/**
+ * gdk_clipboard_set_image:
+ * @clipboard: a #GdkClipboard
+ * @pixbuf: the image to store in the clipboard
+ *
+ * Sets the clipboard content to the given image.
+ *
+ * The clipboard takes a reference on @pixbuf and provides it
+ * to requestors until the clipboard gets overwritten with
+ * new content from this or another process, or until
+ * gdk_clipboard_clear() is called.
+ *
+ * Since: 3.14
+ */
 void
 gdk_clipboard_set_image (GdkClipboard *clipboard,
                          GdkPixbuf    *pixbuf)
@@ -204,6 +377,16 @@ gdk_clipboard_set_image (GdkClipboard *clipboard,
   GDK_CLIPBOARD_GET_CLASS (clipboard)->set_image (clipboard, pixbuf);
 }
 
+/**
+ * gdk_clipboard_image_available:
+ * @clipboard:
+ *
+ * Returns whether the clipboard currently contains an image.
+ *
+ * Returns: %TRUE if the clipboard contains an image
+ *
+ * Since: 3.14
+ */
 gboolean
 gdk_clipboard_image_available (GdkClipboard *clipboard)
 {
@@ -216,6 +399,24 @@ gdk_clipboard_image_available (GdkClipboard *clipboard)
   return (priv->content & IMAGE_CONTENT) != 0;
 }
 
+/**
+ * gdk_clipboard_get_data_async:
+ * @clipboard: a #GdkClipboard
+ * @content_type: the type of content to retrieve
+ * @cancellable: (allow-none): a #GCancellable
+ * @callback: the callback to call when the text is available
+ * @user_data: data that gets passed to @callback
+ *
+ * Retrieves the content of the clipboard with the given content type.
+ * This may involve inter-process communication with the current owner
+ * of the system clipboard. Therefore, it is implemented as an
+ * asynchronous operation. 
+ *
+ * When the asynchronous operation is completed, @callback is called.
+ * It should call gdk_clipboard_get_data_finish() to retrieve the text.
+ *
+ * Since: 3.14
+ */
 void
 gdk_clipboard_get_data_async (GdkClipboard        *clipboard,
                               const gchar         *content_type,
@@ -228,6 +429,24 @@ gdk_clipboard_get_data_async (GdkClipboard        *clipboard,
   GDK_CLIPBOARD_GET_CLASS (clipboard)->get_data_async (clipboard, content_type, cancellable, callback, 
user_data);
 }
 
+/**
+ * gdk_clipboard_get_data_finish:
+ * @clipboard: a #GdkClipboard
+ * @res: the #GAsyncResult
+ * @error: return location for an error
+ *
+ * Obtains the result of a gdk_clipboard_get_data_async() call.
+ * This function may only be called from a callback passed
+ * to gdk_clipboard_get_data_async().
+ *
+ * If the clipboard does not contain content with the type that
+ * was passed to gdk_clipboard_get_data_async(), %NULL is returned.
+ *
+ * Returns: (transfer full): an input stream from which the current
+ *     content of the clipboard can be read
+ *
+ * Since: 3.14
+ */
 GInputStream *
 gdk_clipboard_get_data_finish (GdkClipboard  *clipboard,
                                GAsyncResult  *res,
@@ -238,6 +457,19 @@ gdk_clipboard_get_data_finish (GdkClipboard  *clipboard,
   return GDK_CLIPBOARD_GET_CLASS (clipboard)->get_data_finish (clipboard, res, error);
 }
 
+/**
+ * gdk_clipboard_set_data:
+ * @clipboard: a #GdkClipboard
+ * @content_types: content types that can be provided
+ * @callback: the function that will be called to retrieve the content
+ * @user_data: user data that gets passed to @callback
+ * @destroy: destroy notify for @user_data
+ *
+ * Sets the clipboard content. The content will be retrieved on demand
+ * by the @callback function.
+ *
+ * Since: 3.14
+ */
 void
 gdk_clipboard_set_data (GdkClipboard          *clipboard,
                         const gchar          **content_types,
@@ -250,6 +482,21 @@ gdk_clipboard_set_data (GdkClipboard          *clipboard,
   GDK_CLIPBOARD_GET_CLASS (clipboard)->set_data (clipboard, content_types, callback, user_data, destroy);
 }
 
+/**
+ * gdk_clipboard_clear:
+ * @clipboard: a #GdkClipboard
+ *
+ * Clears the clipboard.
+ *
+ * If the clipboard is currently holding the system clipboard,
+ * this implies that the clipboard will no longer provide content
+ * to other processes. If the system clipboard is currently held
+ * by another process, this call will drop any cached content,
+ * and the next call to get content will retrieve it from the
+ * other process again.
+ *
+ * Since: 3.14
+ */
 void
 gdk_clipboard_clear (GdkClipboard *clipboard)
 {
@@ -296,6 +543,24 @@ get_bytes (GObject      *object,
   g_free (data);
 }
 
+/**
+ * gdk_clipboard_get_bytes_async:
+ * @clipboard: a #GdkClipboard
+ * @content_type: the type of content to retrieve
+ * @cancellable: (allow-none): a #GCancellable
+ * @callback: the callback to call when the text is available
+ * @user_data: data that gets passed to @callback
+ *
+ * Retrieves the content of the clipboard with the given content type
+ * as a #GBytes. This may involve inter-process communication with the
+ * current owner of the system clipboard. Therefore, it is implemented
+ * as an asynchronous operation. 
+ *
+ * When the asynchronous operation is completed, @callback is called.
+ * It should call gdk_clipboard_get_bytes_finish() to retrieve the text.
+ *
+ * Since: 3.14
+ */
 void
 gdk_clipboard_get_bytes_async (GdkClipboard        *clipboard,
                                const gchar         *content_type,
@@ -314,6 +579,24 @@ gdk_clipboard_get_bytes_async (GdkClipboard        *clipboard,
   gdk_clipboard_get_data_async (clipboard, content_type, cancellable, get_bytes, data);
 }
 
+/**
+ * gdk_clipboard_get_bytes_finish:
+ * @clipboard: a #GdkClipboard
+ * @res: the #GAsyncResult
+ * @error: return location for an error
+ *
+ * Obtains the result of a gdk_clipboard_get_bytes_async() call.
+ * This function may only be called from a callback passed
+ * to gdk_clipboard_get_bytes_async().
+ *
+ * If the clipboard does not contain content with the type that
+ * was passed to gdk_clipboard_get_bytes_async(), %NULL is returned.
+ *
+ * Returns: (transfer full): a #GBytes with the current
+ *     content of the clipboard
+ *
+ * Since: 3.14
+ */
 GBytes *
 gdk_clipboard_get_bytes_finish (GdkClipboard  *clipboard,
                                 GAsyncResult  *res,
@@ -357,6 +640,21 @@ set_bytes (GdkClipboard  *clipboard,
   g_bytes_unref (bytes);
 }
 
+/**
+ * gdk_clipboard_set_bytes:
+ * @clipboard: a #GdkClipboard
+ * @bytes: the content in a #GBytes
+ * @content_types: content types that can be provided
+ *
+ * Sets the clipboard content from a #GBytes.
+ *
+ * The clipboard takes a reference on @bytes and provides
+ * its content to requestors until the clipboard gets
+ * overwritten with new content from this or another
+ * process, or until gdk_clipboard_clear() is called.
+ *
+ * Since: 3.14
+ */
 void
 gdk_clipboard_set_bytes (GdkClipboard *clipboard,
                          GBytes       *bytes,
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index a52276c..1f249bf 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -2226,6 +2226,18 @@ gdk_error_trap_pop (void)
   return gdk_error_trap_pop_internal (TRUE);
 }
 
+/**
+ * gdk_display_get_clipboard:
+ * @display: a #GdkDisplay
+ *
+ * Returns the #GdkClipboard for this display. This is a per-display
+ * singleton object and is backed by the system CLIPBOARD, if the
+ * platform supports it.
+ *
+ * Returns: (transfer none): the #GdkClipboard representing the system CLIPBOARD
+ *
+ * Since: 3.14
+ */
 GdkClipboard *
 gdk_display_get_clipboard (GdkDisplay *display)
 {
@@ -2234,6 +2246,19 @@ gdk_display_get_clipboard (GdkDisplay *display)
   return GDK_DISPLAY_GET_CLASS (display)->get_clipboard (display);
 }
 
+/**
+ * gdk_display_get_primary:
+ * @display: a #GdkDisplay
+ *
+ * Returns the 'primary' #GdkClipboard for this display. This is a
+ * per-display singleton object and is backed by the system PRIMARY clipboard,
+ * if the platform supports it.
+ *
+ * Returns: (transfer none): the #GdkClipboard representing the system
+ *     PRIMARY clipboard
+ *
+ * Since: 3.14
+ */
 GdkClipboard *
 gdk_display_get_primary (GdkDisplay *display)
 {