[gtk+/treeview-refactor: 244/257] docs: Move documentation to inline comments: gdkselection

[Tristan Van Berkom <tvb src gnome org>]

commit 7090aa1e1bf666cb68cafb6173ebd7c80861f157
Author: Javier Jardón <jjardon gnome org>
Date:   Mon Nov 15 17:20:51 2010 +0100

    docs: Move documentation to inline comments: gdkselection

 docs/reference/gdk/tmpl/.gitignore      |    1 +
 docs/reference/gdk/tmpl/selections.sgml |  279 -------------------------------
 gdk/gdkselection.c                      |   75 ++++++++
 gdk/gdkselection.h                      |  109 ++++++++++++
 4 files changed, 185 insertions(+), 279 deletions(-)
---
diff --git a/docs/reference/gdk/tmpl/.gitignore b/docs/reference/gdk/tmpl/.gitignore
index 4341431..e835592 100644
--- a/docs/reference/gdk/tmpl/.gitignore
+++ b/docs/reference/gdk/tmpl/.gitignore
@@ -12,5 +12,6 @@ keys.sgml
 pango_interaction.sgml
 pixbufs.sgml
 regions.sgml
+selections.sgml
 visuals.sgml
 windows.sgml
diff --git a/gdk/gdkselection.c b/gdk/gdkselection.c
index eed340a..fc191aa 100644
--- a/gdk/gdkselection.c
+++ b/gdk/gdkselection.c
@@ -32,6 +32,54 @@
 #include "gdkdisplay.h"
 
 
+/**
+ * SECTION:selections
+ * @Short_description: Functions for transfering data via the X selection mechanism
+ * @Title: Selections
+ *
+ * The X selection mechanism provides a way to transfer arbitrary chunks of
+ * data between programs. A <firstterm>selection</firstterm> is a essentially
+ * a named clipboard, identified by a string interned as a #GdkAtom. By
+ * claiming ownership of a selection, an application indicates that it will
+ * be responsible for supplying its contents. The most common selections are
+ * <literal>PRIMARY</literal> and <literal>CLIPBOARD</literal>.
+ *
+ * The contents of a selection can be represented in a number of formats,
+ * called <firstterm>targets</firstterm>. Each target is identified by an atom.
+ * A list of all possible targets supported by the selection owner can be
+ * retrieved by requesting the special target <literal>TARGETS</literal>. When
+ * a selection is retrieved, the data is accompanied by a type (an atom), and
+ * a format (an integer, representing the number of bits per item).
+ * See <link linkend="gdk-Properties-and-Atoms">Properties and Atoms</link>
+ * for more information.
+ *
+ * The functions in this section only contain the lowlevel parts of the
+ * selection protocol. A considerably more complicated implementation is needed
+ * on top of this. GTK+ contains such an implementation in the functions in
+ * <literal>gtkselection.h</literal> and programmers should use those functions
+ * instead of the ones presented here. If you plan to implement selection
+ * handling directly on top of the functions here, you should refer to the
+ * X Inter-client Communication Conventions Manual (ICCCM).
+ */
+
+/**
+ * gdk_selection_owner_set:
+ * @owner: a #GdkWindow or %NULL to indicate that the
+ *   the owner for the given should be unset.
+ * @selection: an atom identifying a selection.
+ * @time_: timestamp to use when setting the selection.
+ *   If this is older than the timestamp given last
+ *   time the owner was set for the given selection, the
+ *   request will be ignored.
+ * @send_event: if %TRUE, and the new owner is different
+ *   from the current owner, the current owner
+ *   will be sent a SelectionClear event.
+ *
+ * Sets the owner of the given selection.
+ *
+ * Returns: %TRUE if the selection owner was successfully
+ *   changed to @owner, otherwise %FALSE.
+ */
 gboolean
 gdk_selection_owner_set (GdkWindow *owner,
 			 GdkAtom    selection,
@@ -43,6 +91,21 @@ gdk_selection_owner_set (GdkWindow *owner,
 					      time, send_event);
 }
 
+/**
+ * gdk_selection_owner_get:
+ * @selection: an atom indentifying a selection.
+ *
+ * Determines the owner of the given selection.
+ *
+ * Returns: if there is a selection owner for this window,
+ *   and it is a window known to the current process,
+ *   the #GdkWindow that owns the selection, otherwise
+ *   %NULL. Note that the return value may be owned
+ *   by a different process if a foreign window
+ *   was previously created for that window, but
+ *   a new foreign window will never be created by
+ *   this call.
+ */
 GdkWindow*
 gdk_selection_owner_get (GdkAtom selection)
 {
@@ -50,6 +113,18 @@ gdk_selection_owner_get (GdkAtom selection)
 					      selection);
 }
 
+/**
+ * gdk_selection_send_notify:
+ * @requestor: window to which to deliver response.
+ * @selection: selection that was requested.
+ * @target: target that was selected.
+ * @property: property in which the selection owner stored the
+ *   data, or %GDK_NONE to indicate that the request
+ *   was rejected.
+ * @time_: timestamp.
+ *
+ * Sends a response to SelectionRequest event.
+ */
 void
 gdk_selection_send_notify (GdkNativeWindow requestor,
 			   GdkAtom         selection,
diff --git a/gdk/gdkselection.h b/gdk/gdkselection.h
index fc5d4b4..897e0c7 100644
--- a/gdk/gdkselection.h
+++ b/gdk/gdkselection.h
@@ -38,21 +38,116 @@ G_BEGIN_DECLS
 /* Predefined atoms relating to selections. In general, one will need to use
  * gdk_intern_atom
  */
+/**
+ * GDK_SELECTION_PRIMARY:
+ *
+ * A #GdkAtom representing the <literal>PRIMARY</literal> selection.
+ */
 #define GDK_SELECTION_PRIMARY 		_GDK_MAKE_ATOM (1)
+
+/**
+ * GDK_SELECTION_SECONDARY:
+ *
+ * A #GdkAtom representing the <literal>SECONDARY</literal> selection.
+ */
 #define GDK_SELECTION_SECONDARY 	_GDK_MAKE_ATOM (2)
+
+/**
+ * GDK_SELECTION_CLIPBOARD:
+ *
+ * A #GdkAtom representing the <literal>CLIPBOARD</literal> selection.
+ */
 #define GDK_SELECTION_CLIPBOARD 	_GDK_MAKE_ATOM (69)
+
+/**
+ * GDK_TARGET_BITMAP:
+ *
+ * A #GdkAtom representing the <literal>BITMAP</literal> selection target.
+ */
 #define GDK_TARGET_BITMAP 		_GDK_MAKE_ATOM (5)
+
+/**
+ * GDK_TARGET_COLORMAP:
+ *
+ * A #GdkAtom representing the <literal>COLORMAP</literal> selection target.
+ */
 #define GDK_TARGET_COLORMAP 		_GDK_MAKE_ATOM (7)
+
+/**
+ * GDK_TARGET_DRAWABLE:
+ *
+ * A #GdkAtom representing the <literal>DRAWABLE</literal> selection target.
+ */
 #define GDK_TARGET_DRAWABLE 		_GDK_MAKE_ATOM (17)
+
+/**
+ * GDK_TARGET_PIXMAP:
+ *
+ * A #GdkAtom representing the <literal>PIXMAP</literal> selection target.
+ */
 #define GDK_TARGET_PIXMAP 		_GDK_MAKE_ATOM (20)
+
+/**
+ * GDK_TARGET_STRING:
+ *
+ * A #GdkAtom representing the <literal>STRING</literal> selection target.
+ */
 #define GDK_TARGET_STRING 		_GDK_MAKE_ATOM (31)
+
+/**
+ * GDK_SELECTION_TYPE_ATOM:
+ *
+ * A #GdkAtom representing the <literal>ATOM</literal> selection type.
+ */
 #define GDK_SELECTION_TYPE_ATOM 	_GDK_MAKE_ATOM (4)
+
+/**
+ * GDK_SELECTION_TYPE_BITMAP:
+ *
+ * A #GdkAtom representing the <literal>BITMAP</literal> selection type.
+ */
 #define GDK_SELECTION_TYPE_BITMAP 	_GDK_MAKE_ATOM (5)
+
+/**
+ * GDK_SELECTION_TYPE_COLORMAP:
+ *
+ * A #GdkAtom representing the <literal>COLORMAP</literal> selection type.
+ */
 #define GDK_SELECTION_TYPE_COLORMAP 	_GDK_MAKE_ATOM (7)
+
+/**
+ * GDK_SELECTION_TYPE_DRAWABLE:
+ *
+ * A #GdkAtom representing the <literal>DRAWABLE</literal> selection type.
+ */
 #define GDK_SELECTION_TYPE_DRAWABLE 	_GDK_MAKE_ATOM (17)
+
+/**
+ * GDK_SELECTION_TYPE_INTEGER:
+ *
+ * A #GdkAtom representing the <literal>INTEGER</literal> selection type.
+ */
 #define GDK_SELECTION_TYPE_INTEGER 	_GDK_MAKE_ATOM (19)
+
+/**
+ * GDK_SELECTION_TYPE_PIXMAP:
+ *
+ * A #GdkAtom representing the <literal>PIXMAP</literal> selection type.
+ */
 #define GDK_SELECTION_TYPE_PIXMAP 	_GDK_MAKE_ATOM (20)
+
+/**
+ * GDK_SELECTION_TYPE_WINDOW:
+ *
+ * A #GdkAtom representing the <literal>WINDOW</literal> selection type.
+ */
 #define GDK_SELECTION_TYPE_WINDOW 	_GDK_MAKE_ATOM (33)
+
+/**
+ * GDK_SELECTION_TYPE_STRING:
+ *
+ * A #GdkAtom representing the <literal>STRING</literal> selection type.
+ */
 #define GDK_SELECTION_TYPE_STRING 	_GDK_MAKE_ATOM (31)
 
 /* Selections
@@ -74,6 +169,20 @@ gboolean   gdk_selection_owner_set_for_display (GdkDisplay *display,
 GdkWindow *gdk_selection_owner_get_for_display (GdkDisplay *display,
 						GdkAtom     selection);
 
+/**
+ * gdk_selection_convert:
+ * @requestor: a #GdkWindow.
+ * @selection: an atom identifying the selection to get the
+ *   contents of.
+ * @target: the form in which to retrieve the selection.
+ * @time_: the timestamp to use when retrieving the
+ *   selection. The selection owner may refuse the
+ *   request if it did not own the selection at
+ *   the time indicated by the timestamp.
+ *
+ * Retrieves the contents of a selection in a given
+ * form.
+ */
 void	   gdk_selection_convert   (GdkWindow	 *requestor,
 				    GdkAtom	  selection,
 				    GdkAtom	  target,