Make EosActionButton public and document it

Rename eosactionbutton-private.h to eosactionbutton.h, make sure it gets picked
up in the documentation, include it in endless.h, make all the new public API
documentation complete, and put the EosActionButtonSize enum documentation on
the EosActionButton page.
[endlessm/eos-sdk#133]

6 files changed, 127 insertions, 5 deletions

diff --git a/endless/Makefile.am b/endless/Makefile.am
index 77f8c95..db6022c 100644
--- a/endless/Makefile.am
+++ b/endless/Makefile.am
@@ -4,6 +4,7 @@ endless_public_installed_headers = endless/endless.h
 
 endless_private_installed_headers = \
 	endless/eosversion.h \
+	endless/eosactionbutton.h \
 	endless/eosapplication.h \
 	endless/eosenums.h \
 	endless/eosmacros.h \
@@ -11,7 +12,6 @@ endless_private_installed_headers = \
 	endless/eossplashpagemanager.h \
 	endless/eostypes.h \
 	endless/eoswindow.h \
-	endless/eosactionbutton-private.h \
 	endless/eosactionmenu-private.h
 
 endless_library_sources = \
diff --git a/endless/endless.h b/endless/endless.h
index 6e9d46e..afc30e7 100644
--- a/endless/endless.h
+++ b/endless/endless.h
@@ -12,6 +12,7 @@ G_BEGIN_DECLS
 
 /* Pull in other header files */
 #include "eostypes.h"
+#include "eosactionbutton.h"
 #include "eosapplication.h"
 #include "eospagemanager.h"
 #include "eossplashpagemanager.h"
diff --git a/endless/eosactionbutton.c b/endless/eosactionbutton.c
index 14106d4..148cd2b 100644
--- a/endless/eosactionbutton.c
+++ b/endless/eosactionbutton.c
@@ -1,12 +1,37 @@
 /* Copyright 2013 Endless Mobile, Inc. */
 
 #include "config.h"
-#include "eosactionbutton-private.h"
+#include "eosactionbutton.h"
 
 #include <glib-object.h>
 #include <gtk/gtk.h>
 #include <math.h>
 
+/**
+ * SECTION:action-button
+ * @short_description: Buttons that the user recognizes as performing actions
+ * @title: Action buttons
+ *
+ * Any time you want to inform your user which actions are available, use an
+ * action button.
+ * For example, suppose you had a page in your application where the user could
+ * draw a picture.
+ * After finishing the picture, the user could save it or share it on Facebook.
+ * In that case, you would use two action buttons, labeled for example
+ * <quote>SAVE</quote> and <quote>SHARE</quote>, and containing icons
+ * representing saving and sharing.
+ *
+ * The buttons have a recognizable style and round border, so that it is
+ * instantly clear to the user that they represent actions.
+ *
+ * Generally, you should set the #EosPageManager:actions property on the page
+ * that you want to use action buttons on; this neatly arranges the actions
+ * in an action area on the right-hand side of the screen, placing the main
+ * action in a prominent place, and actions such as <quote>cancel</quote> on the
+ * bottom.
+ * However, you can also manually place action buttons anywhere on a page.
+ */
+
 #define _EOS_STYLE_CLASS_ACTION_BUTTON "action-button"
 
 G_DEFINE_TYPE (EosActionButton, eos_action_button, GTK_TYPE_BUTTON)
@@ -102,6 +127,14 @@ eos_action_button_class_init (EosActionButtonClass *klass)
   widget_class->get_preferred_width  = eos_action_button_get_preferred_width;
   widget_class->get_preferred_height = eos_action_button_get_preferred_height;
 
+  /**
+   * EosActionButton:size:
+   *
+   * Size for the action button; use #EosActionButtonSize to specify that the
+   * button represents a primary action, secondary, tertiary, or quaternary.
+   * #EOS_ACTION_BUTTON_SIZE_PRIMARY is the largest, and
+   * #EOS_ACTION_BUTTON_SIZE_QUATERNARY is the smallest (seldom used.)
+   */
   g_object_class_install_property (object_class,
                                    PROP_SIZE,
                                    g_param_spec_int ("size",
@@ -112,6 +145,11 @@ eos_action_button_class_init (EosActionButtonClass *klass)
                                                      EOS_ACTION_BUTTON_SIZE_SECONDARY,
                                                      G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
 
+  /**
+   * EosActionButton:label:
+   *
+   * Text for the label that is placed below or to the side of the button.
+   */
   g_object_class_install_property (object_class,
                                    PROP_LABEL,
                                    g_param_spec_string ("label",
@@ -120,6 +158,11 @@ eos_action_button_class_init (EosActionButtonClass *klass)
                                                         NULL,
                                                         G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
 
+  /**
+   * EosActionButton:icon-id:
+   *
+   * Icon name for the icon that is drawn within the circular button.
+   */
   g_object_class_install_property (object_class,
                                    PROP_ICON_ID,
                                    g_param_spec_string ("icon-id",
@@ -195,6 +238,17 @@ eos_action_button_init (EosActionButton *self)
 
 /* ******* LIFECYCLE ******* */
 
+/**
+ * eos_action_button_new:
+ * @size: size for the button: primary, secondary, et cetera
+ * @label: text to place under or beside the action button
+ * @icon_id: icon name for the icon inside the action button
+ *
+ * Convenience function for creating an action button with the size, label, and
+ * icon already set.
+ *
+ * Returns: a pointer to the newly-created widget.
+ */
 GtkWidget *
 eos_action_button_new (EosActionButtonSize size,
                        const gchar *label,
@@ -277,6 +331,14 @@ eos_action_button_load_icon (EosActionButton *button)
   gtk_image_set_from_pixbuf (GTK_IMAGE (priv->icon_image), priv->icon_pixbuf);
 }
 
+/**
+ * eos_action_button_set_size:
+ * @button: the button
+ * @size: a value from #EosActionButtonSize
+ *
+ * Sets the size of the button (e.g. secondary).
+ * See #EosActionButton:size for more information.
+ */
 void
 eos_action_button_set_size  (EosActionButton *button,
                              EosActionButtonSize size)
@@ -305,6 +367,15 @@ eos_action_button_set_size  (EosActionButton *button,
     }
 }
 
+/**
+ * eos_action_button_get_size:
+ * @button: the button
+ *
+ * Gets the size of the button (e.g. secondary).
+ * See #EosActionButton:size for more information.
+ *
+ * Returns: the size as a value from #EosActionButtonSize
+ */
 EosActionButtonSize
 eos_action_button_get_size (EosActionButton *button)
 {
@@ -317,6 +388,14 @@ eos_action_button_get_size (EosActionButton *button)
   return priv->size;
 }
 
+/**
+ * eos_action_button_set_label:
+ * @button: the button
+ * @label: text for the label
+ *
+ * Sets the text showing below or beside the button.
+ * See #EosActionButton:label for more information.
+ */
 void
 eos_action_button_set_label (EosActionButton *button, const gchar *label)
 {
@@ -335,6 +414,15 @@ eos_action_button_set_label (EosActionButton *button, const gchar *label)
   g_object_notify (G_OBJECT (button), "label");
 }
 
+/**
+ * eos_action_button_get_label:
+ * @button: the button
+ *
+ * Gets the text showing below or beside the button.
+ * See #EosActionButton:label for more information.
+ *
+ * Returns: the label text
+ */
 const gchar *
 eos_action_button_get_label (EosActionButton *button)
 {
@@ -347,6 +435,14 @@ eos_action_button_get_label (EosActionButton *button)
   return priv->label;
 }
 
+/**
+ * eos_action_button_set_icon_id:
+ * @button: the button
+ * @icon_id: an icon name
+ *
+ * Sets a new icon showing in the button, specified by icon name.
+ * See #EosActionButton:icon-id for more information.
+ */
 void
 eos_action_button_set_icon_id (EosActionButton *button,
                                const gchar* icon_id)
@@ -366,6 +462,15 @@ eos_action_button_set_icon_id (EosActionButton *button,
     }
 }
 
+/**
+ * eos_action_button_get_icon_id:
+ * @button: the button
+ *
+ * Gets the icon name for the icon showing in the button.
+ * See #EosActionButton:icon-id for more information.
+ *
+ * Returns: an icon name
+ */
 const gchar *
 eos_action_button_get_icon_id (EosActionButton *button)
 {
diff --git a/endless/eosactionbutton-private.h b/endless/eosactionbutton.h
index 27dcb62..ad9c4cb 100644
--- a/endless/eosactionbutton-private.h
+++ b/endless/eosactionbutton.h
@@ -35,6 +35,11 @@ typedef struct _EosActionButton EosActionButton;
 typedef struct _EosActionButtonClass EosActionButtonClass;
 typedef struct _EosActionButtonPrivate EosActionButtonPrivate;
 
+/**
+ * EosActionButton:
+ *
+ * This class structure contains no public members.
+ */
 struct _EosActionButton
 {
   GtkButton parent;
@@ -45,27 +50,38 @@ struct _EosActionButton
 struct _EosActionButtonClass
 {
   GtkButtonClass parent_class;
+
+  /* For further expansion */
+  gpointer _padding[8];
 };
 
+EOS_SDK_ALL_API_VERSIONS
 GType               eos_action_button_get_type    (void) G_GNUC_CONST;
 
+EOS_SDK_ALL_API_VERSIONS
 GtkWidget          *eos_action_button_new         (EosActionButtonSize size,
                                                    const gchar        *label,
                                                    const gchar        *icon_id);
 
+EOS_SDK_ALL_API_VERSIONS
 void                eos_action_button_set_size    (EosActionButton    *button,
                                                    EosActionButtonSize size);
 
+EOS_SDK_ALL_API_VERSIONS
 EosActionButtonSize eos_action_button_get_size    (EosActionButton    *button);
 
+EOS_SDK_ALL_API_VERSIONS
 void                eos_action_button_set_label   (EosActionButton    *button,
                                                    const gchar        *label);
 
+EOS_SDK_ALL_API_VERSIONS
 const gchar        *eos_action_button_get_label   (EosActionButton    *button);
 
+EOS_SDK_ALL_API_VERSIONS
 void                eos_action_button_set_icon_id (EosActionButton    *button,
-                                                   const gchar        *stock_id);
+                                                   const gchar        *icon_id);
 
+EOS_SDK_ALL_API_VERSIONS
 const gchar        *eos_action_button_get_icon_id (EosActionButton    *button);
 
 G_END_DECLS
diff --git a/endless/eosactionmenu.c b/endless/eosactionmenu.c
index 98ae77d..e3466e2 100644
--- a/endless/eosactionmenu.c
+++ b/endless/eosactionmenu.c
@@ -3,7 +3,7 @@
 #include "config.h"
 #include "eosactionmenu-private.h"
 
-#include "eosactionbutton-private.h"
+#include "eosactionbutton.h"
 #include <glib-object.h>
 #include <gtk/gtk.h>
 #include <math.h>
diff --git a/endless/eosenums.h b/endless/eosenums.h
index 873213d..824c99a 100644
--- a/endless/eosenums.h
+++ b/endless/eosenums.h
@@ -9,7 +9,7 @@
 
 /* Shared typedefs for enumerations */
 
-/**
+/*
  * SECTION:enums
  * @Short_description: Public enumerated types used throughout the Endless SDK
  * @Title: Standard Enumerations