Create/clarify some documentation in the custom widgets.

4 files changed, 52 insertions, 17 deletions

diff --git a/widgets/src/BaseWindow.c b/widgets/src/BaseWindow.c
index f417260ef..7493ca45e 100644
--- a/widgets/src/BaseWindow.c
+++ b/widgets/src/BaseWindow.c
@@ -133,6 +133,8 @@ static void anaconda_base_window_class_init(AnacondaBaseWindowClass *klass) {
      *
      * The name of the currently displayed window, displayed in the upper
      * left corner of all windows with a title throughout installation.
+     * StandaloneWindows should not have a title, so no name will be displayed
+     * for those.
      *
      * Since: 1.0
      */
@@ -151,7 +153,8 @@ static void anaconda_base_window_class_init(AnacondaBaseWindowClass *klass) {
      * @window: the window that received the signal
      *
      * Emitted when a visible info bar at the bottom of the window has been clicked
-     * (pressed and released).
+     * (pressed and released).  This allows, for instance, popping up a dialog with
+     * more detailed information.
      *
      * Since: 1.0
      */
@@ -189,6 +192,9 @@ static void anaconda_base_window_init(AnacondaBaseWindow *win) {
     win->priv->is_beta = FALSE;
     win->priv->info_shown = FALSE;
 
+    /* These store the original English strings so that when we retranslate
+     * later, we have the source strings available to feed into _().
+     */
     win->priv->orig_name = NULL;
     win->priv->orig_distro = NULL;
     win->priv->orig_beta = NULL;
@@ -259,7 +265,7 @@ static void anaconda_base_window_init(AnacondaBaseWindow *win) {
 
     win->priv->orig_distro = g_strdup(DEFAULT_DISTRIBUTION);
 
-    /* Create the betanag label. */
+    /* Create the beta label. */
     win->priv->beta_label = gtk_label_new(NULL);
     markup = g_markup_printf_escaped("<span foreground='red' weight='bold' size='large'>%s</span>", _(DEFAULT_BETA));
     gtk_label_set_markup(GTK_LABEL(win->priv->beta_label), markup);
@@ -323,7 +329,7 @@ static void anaconda_base_window_set_property(GObject *object, guint prop_id, co
  * anaconda_base_window_get_beta:
  * @win: a #AnacondaBaseWindow
  *
- * Returns whether or not this window is set to display the betanag warning.
+ * Returns whether or not this window is set to display the beta label.
  *
  * Returns: Whether @win is set to display the betanag warning
  *
@@ -338,8 +344,8 @@ gboolean anaconda_base_window_get_beta(AnacondaBaseWindow *win) {
  * @win: a #AnacondaBaseWindow
  * @is_beta: %TRUE to display the betanag warning
  *
- * Sets up the window to display the betanag warning in red along the top of
- * the screen.
+ * Sets up the window to display the beta label in red along the top of the
+ * screen.
  *
  * Since: 1.0
  */
@@ -356,7 +362,8 @@ void anaconda_base_window_set_beta(AnacondaBaseWindow *win, gboolean is_beta) {
  * anaconda_base_window_get_action_area:
  * @win: a #AnacondaBaseWindow
  *
- * Returns the action area of @win.
+ * Returns the action area of @win.  This is the area of the screen where most
+ * of the widgets the user interacts with will live.
  *
  * Returns: (transfer none): The action area
  *
@@ -370,7 +377,9 @@ GtkWidget *anaconda_base_window_get_action_area(AnacondaBaseWindow *win) {
  * anaconda_base_window_get_nav_area:
  * @win: a #AnacondaBaseWindow
  *
- * Returns the navigation area of @win.
+ * Returns the navigation area of @win.  This is the area at the top of the
+ * screen displaying the window's title (if it has one), distribution, and
+ * so forth.
  *
  * Returns: (transfer none): The navigation area
  *
@@ -385,6 +394,8 @@ GtkWidget *anaconda_base_window_get_nav_area(AnacondaBaseWindow *win) {
  * @win: a #AnacondaBaseWindow
  *
  * Returns the event box that houses background window of the navigation area of @win.
+ * Currently, this is only used by #AnacondaSpokeWindow to have a place to store the
+ * gradient image.  This function should probably not be used elsewhere.
  *
  * Returns: (transfer none): The event box
  *
@@ -398,7 +409,10 @@ GtkWidget *anaconda_base_window_get_nav_area_background_window(AnacondaBaseWindo
  * anaconda_base_window_get_main_box:
  * @win: a #AnacondaBaseWindow
  *
- * Returns the main content area of @win.
+ * Returns the main content area of @win.  This widget holds both the action_area
+ * and the nav_area.  Currently, this is only used by #AnacondaStandaloneWindow
+ * as a place to store the extra Continue button.  This function should probably
+ * not be used elsewhere.
  *
  * Returns: (transfer none): The main content area
  *
@@ -412,7 +426,9 @@ GtkWidget *anaconda_base_window_get_main_box(AnacondaBaseWindow *win) {
  * anaconda_base_window_get_alignment:
  * @win: a #AnacondaBaseWindow
  *
- * Returns the internal alignment widget of @win.
+ * Returns the internal alignment widget of @win.  Currently, this is only used
+ * by #AnacondaHubWindow to set different alignment values than the spokes have.
+ * This function should probably not be used elsewhere.
  *
  * Returns: (transfer none): The alignment widget
  *
@@ -553,6 +569,7 @@ void anaconda_base_window_retranslate(AnacondaBaseWindow *win, const char *lang)
     setenv("LANGUAGE", lang, 1);
     setlocale(LC_ALL, "");
 
+    /* This bit is internal gettext magic. */
     {
         extern int _nl_msg_cat_cntr;
         ++_nl_msg_cat_cntr;
@@ -594,6 +611,10 @@ static GObject *
 anaconda_base_window_buildable_get_internal_child (GtkBuildable *buildable,
                                                    GtkBuilder *builder,
                                                    const gchar *childname) {
+    /* Note that if you add more internal children and want them to be accessible,
+     * all their parents must also be made accessible.  This goes all the way up
+     * to the top level.
+     */
     if (!strcmp(childname, "main_box"))
         return G_OBJECT(anaconda_base_window_get_main_box(ANACONDA_BASE_WINDOW(buildable)));
     else if (!strcmp(childname, "nav_area"))
diff --git a/widgets/src/MountpointSelector.c b/widgets/src/MountpointSelector.c
index 160c43fe7..3b9a09fbf 100644
--- a/widgets/src/MountpointSelector.c
+++ b/widgets/src/MountpointSelector.c
@@ -31,7 +31,7 @@
  * @short_description: A graphical way to select a mount point.
  *
  * A #AnacondaMountpointSelector is a widget that appears on the custom partitioning
- * Mountpoint and allows the user to select a single mount point to do additional
+ * spoke and allows the user to select a single mount point to do additional
  * configuration.
  *
  * As a #AnacondaMountpointSelector is a subclass of a #GtkEventBox, any signals
diff --git a/widgets/src/SpokeSelector.c b/widgets/src/SpokeSelector.c
index e6c23cc2e..c459667a7 100644
--- a/widgets/src/SpokeSelector.c
+++ b/widgets/src/SpokeSelector.c
@@ -35,7 +35,7 @@
  * configuration and allows for a place to click to do further configuration.
  *
  * Some Spokes can have their initial configuration guessed, while others
- * (specifically storage) requires the user to do something.  For those that
+ * (specifically storage) require the user to do something.  For those that
  * the user has not entered, the selector may be set as incomplete.  See
  * #anaconda_spoke_selector_get_incomplete and #anaconda_spoke_selector_set_incomplete.
  *
@@ -103,7 +103,8 @@ static void anaconda_spoke_selector_class_init(AnacondaSpokeSelectorClass *klass
      * The :status string is text displayed underneath the spoke's :title and
      * also beside the :icon.  This text very briefly describes what has been
      * selected on the spoke associated with this selector.  For instance, it
-     * might be set up to "English" for a language-related spoke.
+     * might be set up to "English" for a language-related spoke.  Special
+     * formatting will be applied to error status text for incomplete spokes.
      *
      * Since: 1.0
      */
@@ -119,7 +120,9 @@ static void anaconda_spoke_selector_class_init(AnacondaSpokeSelectorClass *klass
      * AnacondaSpokeSelector:title:
      *
      * The :title of this selector, which will be displayed large and bold
-     * beside the :icon.
+     * beside the :icon.  The title string should contain a keyboard mnemonic
+     * (a letter preceeded by an underscore), in which case this will be the
+     * keystroke that can be used to focus this selector.
      *
      * Since: 1.0
      */
@@ -155,6 +158,7 @@ static void format_status_label(AnacondaSpokeSelector *spoke, const char *markup
     pango_attr_list_insert(attrs, pango_attr_style_new(PANGO_STYLE_ITALIC));
     pango_attr_list_insert(attrs, pango_attr_scale_new(PANGO_SCALE_LARGE));
 
+    /* Display error text in a dark red color to draw the user's attention. */
     if (anaconda_spoke_selector_get_incomplete(spoke) &&
         gtk_widget_get_sensitive(GTK_WIDGET(spoke))) {
         pango_attr_list_insert(attrs, pango_attr_foreground_new(0xcccc, 0x1a1a, 0x1a1a));
@@ -208,6 +212,13 @@ static void anaconda_spoke_selector_init(AnacondaSpokeSelector *spoke) {
     gtk_widget_set_valign(spoke->priv->icon, GTK_ALIGN_CENTER);
     gtk_misc_set_padding(GTK_MISC(spoke->priv->icon), 12, 0);
 
+    /* This little warning icon will be displayed near the title when the
+     * spoke is incomplete.  We just make it here in advance so we don't have
+     * to make/destroy it on demand.
+     */
+    /* FIXME: This should really be displayed over the corner of the spoke's
+     * icon because it looks like it's floating off in space right now.
+     */
     spoke->priv->incomplete_icon = gtk_image_new_from_icon_name("dialog-warning-symbolic", GTK_ICON_SIZE_MENU);
     gtk_widget_set_no_show_all(GTK_WIDGET(spoke->priv->incomplete_icon), TRUE);
     gtk_widget_set_visible(GTK_WIDGET(spoke->priv->incomplete_icon), FALSE);
diff --git a/widgets/src/SpokeWindow.c b/widgets/src/SpokeWindow.c
index 2874e586a..2db0efef6 100644
--- a/widgets/src/SpokeWindow.c
+++ b/widgets/src/SpokeWindow.c
@@ -77,8 +77,8 @@ static void anaconda_spoke_window_class_init(AnacondaSpokeWindowClass *klass) {
      * AnacondaSpokeWindow:button-label:
      *
      * The :button-label string is the text used to label the button displayed
-     * in the upper lefthand of the window.  By default, this is a back button
-     * but could be anything else appropriate.
+     * in the upper lefthand of the window.  By default, this button says Done,
+     * but it could be changed to anything appropriate.
      *
      * Since: 1.0
      */
@@ -96,7 +96,10 @@ static void anaconda_spoke_window_class_init(AnacondaSpokeWindowClass *klass) {
      *
      * Emitted when the button in the upper left corner has been activated
      * (pressed and released).  This is commonly the button that takes the user
-     * back to the hub, but could do other things.
+     * back to the hub, but could do other things.  Note that we do not want
+     * to trap people in spokes, so there should always be a way back to the
+     * hub via this signal, even if it involves canceling some operation or
+     * resetting things.
      *
      * Since: 1.0
      */
@@ -136,7 +139,7 @@ static void anaconda_spoke_window_init(AnacondaSpokeWindow *win) {
     /* Set some default properties. */
     gtk_window_set_modal(GTK_WINDOW(win), TRUE);
 
-    /* Create the buttons. */
+    /* Create the button. */
     win->priv->button = gtk_button_new_with_mnemonic(DEFAULT_BUTTON_LABEL);
     gtk_widget_set_halign(win->priv->button, GTK_ALIGN_START);