[gtk+] Migrate GtkActionGroup API docs

[Javier Jardón <jjardon src gnome org>]

commit 75e75cd3050fd974e097ab4b7a801e59823fad85
Author: Tadej Borovšak <tadeboro gmail com>
Date:   Sat Jul 3 23:16:39 2010 +0200

    Migrate GtkActionGroup API docs

 docs/reference/gtk/tmpl/.gitignore          |    1 +
 docs/reference/gtk/tmpl/gtkactiongroup.sgml |  401 ---------------------------
 docs/reference/gtk/tmpl/gtkfontsel.sgml     |    5 -
 gtk/gtkactiongroup.c                        |   60 ++++
 gtk/gtkactiongroup.h                        |   51 ++++
 5 files changed, 112 insertions(+), 406 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 0c6b10c..d5efd9d 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -1,3 +1,4 @@
+gtkactiongroup.sgml
 gtkbbox.sgml
 gtkbox.sgml
 gtkbuilder.sgml
diff --git a/docs/reference/gtk/tmpl/gtkfontsel.sgml b/docs/reference/gtk/tmpl/gtkfontsel.sgml
index ce3ebf3..f97de24 100644
--- a/docs/reference/gtk/tmpl/gtkfontsel.sgml
+++ b/docs/reference/gtk/tmpl/gtkfontsel.sgml
@@ -48,11 +48,6 @@ only be accessed using the functions below.
 </para>
 
 
-<!-- ##### ARG GtkFontSelection:font ##### -->
-<para>
-
-</para>
-
 <!-- ##### ARG GtkFontSelection:font-name ##### -->
 <para>
 
diff --git a/gtk/gtkactiongroup.c b/gtk/gtkactiongroup.c
index 658a1ca..4ed7e38 100644
--- a/gtk/gtkactiongroup.c
+++ b/gtk/gtkactiongroup.c
@@ -28,6 +28,66 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+/**
+ * SECTION:gtkactiongroup
+ * @Short_description: A group of actions
+ * @Title: GtkActionGroup
+ *
+ * Actions are organised into groups. An action group is essentially a
+ * map from names to #GtkAction objects.
+ *
+ * All actions that would make sense to use in a particular context
+ * should be in a single group. Multiple action groups may be used for a
+ * particular user interface. In fact, it is expected that most nontrivial
+ * applications will make use of multiple groups. For example, in an
+ * application that can edit multiple documents, one group holding global
+ * actions (e.g. quit, about, new), and one group per document holding
+ * actions that act on that document (eg. save, cut/copy/paste, etc). Each
+ * window's menus would be constructed from a combination of two action
+ * groups.
+ * </para>
+ * <para id="Action-Accel">
+ * Accelerators are handled by the GTK+ accelerator map. All actions are
+ * assigned an accelerator path (which normally has the form
+ * <literal>&lt;Actions&gt;/group-name/action-name</literal>)
+ * and a shortcut is associated with this accelerator path. All menuitems
+ * and toolitems take on this accelerator path. The GTK+ accelerator map
+ * code makes sure that the correct shortcut is displayed next to the menu
+ * item.
+ *
+ * <refsect2 id="GtkActionGroup-BUILDER-UI">
+ * <title>GtkActionGroup as GtkBuildable</title>
+ * <para>
+ * The #GtkActionGroup implementation of the #GtkBuildable interface accepts
+ * #GtkAction objects as &lt;child&gt; elements in UI definitions.
+ *
+ * Note that it is probably more common to define actions and action groups
+ * in the code, since they are directly related to what the code can do.
+ *
+ * The GtkActionGroup implementation of the GtkBuildable interface supports
+ * a custom &lt;accelerator&gt; element, which has attributes named key and
+ * modifiers and allows to specify accelerators. This is similar to the
+ * &lt;accelerator&gt; element of #GtkWidget, the main difference is that
+ * it doesn't allow you to specify a signal.
+ * </para>
+ * <example>
+ * <title>A #GtkDialog UI definition fragment.</title>
+ * <programlisting><![CDATA[
+ * <object class="GtkActionGroup" id="actiongroup">
+ *   <child>
+ *       <object class="GtkAction" id="About">
+ *           <property name="name">About</property>
+ *           <property name="stock_id">gtk-about</property>
+ *           <signal handler="about_activate" name="activate"/>
+ *       </object>
+ *       <accelerator key="F1" modifiers="GDK_CONTROL_MASK | GDK_SHIFT_MASK"/>
+ *   </child>
+ * </object>
+ * ]]></programlisting>
+ * </example>
+ * </refsect2>
+ */
+
 #include "config.h"
 #include <string.h>
 
diff --git a/gtk/gtkactiongroup.h b/gtk/gtkactiongroup.h
index 30d7542..9ac3e38 100644
--- a/gtk/gtkactiongroup.h
+++ b/gtk/gtkactiongroup.h
@@ -77,6 +77,23 @@ struct _GtkActionGroupClass
   void (*_gtk_reserved4) (void);
 };
 
+/**
+ * GtkActionEntry:
+ * @name: The name of the action.
+ * @stock_id: The stock id for the action, or the name of an icon from the
+ *  icon theme.
+ * @label: The label for the action. This field should typically be marked
+ *  for translation, see gtk_action_group_set_translation_domain(). If
+ *  @label is %NULL, the label of the stock item with id @stock_id is used.
+ * @accelerator: The accelerator for the action, in the format understood by
+ *  gtk_accelerator_parse().
+ * @tooltip: The tooltip for the action. This field should typically be
+ *  marked for translation, see gtk_action_group_set_translation_domain().
+ * @callback: The function to call when the action is activated.
+ *
+ * #GtkActionEntry structs are used with gtk_action_group_add_actions() to
+ * construct actions.
+ */
 struct _GtkActionEntry 
 {
   const gchar     *name;
@@ -87,6 +104,23 @@ struct _GtkActionEntry
   GCallback  callback;
 };
 
+/**
+ * GtkToggleActionEntry:
+ * @name: The name of the action.
+ * @stock_id: The stock id for the action, or the name of an icon from the
+ *  icon theme.
+ * @label: The label for the action. This field should typically be marked
+ *  for translation, see gtk_action_group_set_translation_domain().
+ * @accelerator: The accelerator for the action, in the format understood by
+ *  gtk_accelerator_parse().
+ * @tooltip: The tooltip for the action. This field should typically be
+ *  marked for translation, see gtk_action_group_set_translation_domain().
+ * @callback: The function to call when the action is activated.
+ * @is_active: The initial state of the toggle action.
+ *
+ * #GtkToggleActionEntry structs are used with
+ * gtk_action_group_add_toggle_actions() to construct toggle actions.
+ */
 struct _GtkToggleActionEntry 
 {
   const gchar     *name;
@@ -98,6 +132,23 @@ struct _GtkToggleActionEntry
   gboolean   is_active;
 };
 
+/**
+ * GtkRadioActionEntry:
+ * @name: The name of the action.
+ * @stock_id: The stock id for the action, or the name of an icon from the
+ *  icon theme.
+ * @label: The label for the action. This field should typically be marked
+ *  for translation, see gtk_action_group_set_translation_domain().
+ * @accelerator: The accelerator for the action, in the format understood by
+ *  gtk_accelerator_parse().
+ * @tooltip: The tooltip for the action. This field should typically be
+ *  marked for translation, see gtk_action_group_set_translation_domain().
+ * @value: The value to set on the radio action. See
+ *  gtk_radio_action_get_current_value().
+ *
+ * #GtkRadioActionEntry structs are used with
+ * gtk_action_group_add_radio_actions() to construct groups of radio actions.
+ */
 struct _GtkRadioActionEntry 
 {
   const gchar *name;