Cleaning up the documentation.

diff --git a/ChangeLog.2 b/ChangeLog.2
index 8962bc9..40132c2 100644 (file)
--- a/ChangeLog.2
+++ b/ChangeLog.2
@@ -1,3 +1,16 @@
+2007-01-25  Michael Dominic Kostrzewa  <michael.kostrzewa@nokia.com> 
+
+       * src/hildon-sort-dialog.c:
+       * src/hildon-sort-dialog.h:
+       * src/hildon-time-editor.c:
+       * src/hildon-time-picker.c:
+       * src/hildon-volumebar-range.c:
+       * src/hildon-volumebar.c:
+       * src/hildon-vvolumebar.c:
+       * src/hildon-weekday-picker.c:
+       * src/hildon-window.c:
+       * src/hildon-wizard-dialog.c: Cleaning up the documentation.
+
 2007-01-24  Michael Dominic Kostrzewa  <michael.kostrzewa@nokia.com> 
 
        * src/hildon-program.c:

diff --git a/src/hildon-sort-dialog.c b/src/hildon-sort-dialog.c
index fa2d106..3919817 100644 (file)
--- a/src/hildon-sort-dialog.c
+++ b/src/hildon-sort-dialog.c
@@ -78,6 +78,11 @@ sort_key_changed                                (GtkWidget *widget,
 static void 
 hildon_sort_dialog_finalize                     (GObject *object);
 
+gint 
+hildon_sort_dialog_add_sort_key_with_sorting    (HildonSortDialog *dialog, 
+                                                 const gchar *sort_key, 
+                                                 gboolean sorting);
+
 enum 
 {
     PROP_0,
@@ -104,9 +109,7 @@ sort_key_changed                                (GtkWidget *widget,
     priv->reversed = priv->key_reversed [index];
 }
 
-/*
- * Initialises the sort dialog class.
- */
+/* Initialises the sort dialog class. */
 static void
 hildon_sort_dialog_class_init                   (HildonSortDialogClass *class)
 {
@@ -117,25 +120,35 @@ hildon_sort_dialog_class_init                   (HildonSortDialogClass *class)
     gobject_class->set_property = hildon_sort_dialog_set_property;
     gobject_class->get_property = hildon_sort_dialog_get_property;
     gobject_class->finalize     = (gpointer) hildon_sort_dialog_finalize;
-    
+
+    /**
+     * HildonSortDialog:sort-key:
+     *
+     * The currently active sort key.
+     */
     g_object_class_install_property (gobject_class, PROP_SORT_KEY,
         g_param_spec_int ("sort-key",
                           "Sort Key",
                           "The currently active sort key",
-              G_MININT,
-              G_MAXINT,
+                          G_MININT,
+                          G_MAXINT,
                           0, G_PARAM_READWRITE));
-    
+   
+    /**
+     * HildonSortDialog:sort-order:
+     *
+     * The sort order for the currently active sort key.
+     */
     g_object_class_install_property (gobject_class, PROP_SORT_ORDER,
         g_param_spec_enum ("sort-order",
                           "Sort Order",
                           "The current sorting order",
-              GTK_TYPE_SORT_TYPE,
+                          GTK_TYPE_SORT_TYPE,
                           GTK_SORT_ASCENDING,
-              G_PARAM_READWRITE));
+                          G_PARAM_READWRITE));
 }
 
-gint 
+static gint 
 hildon_sort_dialog_add_sort_key_with_sorting    (HildonSortDialog *dialog, 
                                                  const gchar *sort_key, 
                                                  gboolean sorting)

diff --git a/src/hildon-sort-dialog.h b/src/hildon-sort-dialog.h
index e3b7f55..ec3c268 100644 (file)
--- a/src/hildon-sort-dialog.h
+++ b/src/hildon-sort-dialog.h
@@ -87,10 +87,6 @@ gint
 hildon_sort_dialog_add_sort_key                 (HildonSortDialog *dialog,
                                                  const gchar *sort_key);
 
-gint 
-hildon_sort_dialog_add_sort_key_with_sorting    (HildonSortDialog *dialog, 
-                                                 const gchar *sort_key, 
-                                                 gboolean sorting);
 gint
 hildon_sort_dialog_add_sort_key_reversed        (HildonSortDialog *dialog,
                                                  const gchar *sort_key);

diff --git a/src/hildon-time-editor.c b/src/hildon-time-editor.c
index 9120d1e..80d1007 100644 (file)
--- a/src/hildon-time-editor.c
+++ b/src/hildon-time-editor.c
@@ -253,6 +253,13 @@ hildon_time_editor_inserted_text                (GtkEditable *editable,
                                                  gint *position,
                                                  gpointer user_data);
 
+/**
+ * hildon_time_editor_get_type:
+ *
+ * Initializes and returns the type of a hildon time editor.
+ *
+ * @Returns: GType of #HildonTimeEditor
+ */
 GType G_GNUC_CONST
 hildon_time_editor_get_type                     (void)
 {

diff --git a/src/hildon-time-picker.c b/src/hildon-time-picker.c
index 6d38580..82c23d3 100644 (file)
--- a/src/hildon-time-picker.c
+++ b/src/hildon-time-picker.c
@@ -163,6 +163,13 @@ static const gint                               button_multipliers[WIDGET_GROUP_
     { 0, 0 }
 };
 
+/**
+ * hildon_time_picker_get_type:
+ *
+ * Returns the type of HildonTimePicker.
+ *
+ * Returns: HildonTimePicker type
+ */
 GType G_GNUC_CONST
 hildon_time_picker_get_type                     (void)
 {

diff --git a/src/hildon-volumebar-range.c b/src/hildon-volumebar-range.c
index 5dd84da..e596e98 100644 (file)
--- a/src/hildon-volumebar-range.c
+++ b/src/hildon-volumebar-range.c
@@ -22,12 +22,10 @@
  *
  */
 
-/* 
- * @file hildon-volumebar-range.c
- *
- * This file contains the implementation of the HildonVolumebarRange.
- * This widget is an "workhorse" for #HildonVolumebar widget. 
- * It is not designed to be used as a standalone widget.
+/**
+ * SECTION:hildon-volumebar-range
+ * @short_description: This widget is an "workhorse" for #HildonVolumebar
+ * widget. It is not designed to be used as a standalone widget.
  *
  * Purpose of this widget is to act as an "container" for GtkScale
  * widget. #HildonVolumebarRange changes some event parameters so
@@ -95,6 +93,13 @@ enum
   PROP_LEVEL
 };
 
+/**
+ * hildon_volumebar_range_get_type:
+ *
+ * Initializes and returns the type of a hildon volumebar range.
+ *
+ * @Returns: GType of #HildonVolumebarRange
+ */
 GType G_GNUC_CONST
 hildon_volumebar_range_get_type                 (void)
 {
@@ -137,6 +142,11 @@ hildon_volumebar_range_class_init               (HildonVolumebarRangeClass *volu
     object_class->set_property = hildon_volumebar_range_set_property;
     object_class->get_property = hildon_volumebar_range_get_property; 
 
+    /**
+     * HildonVolumebarRange:level:
+     *
+     * Current volume level. 
+     */
     g_object_class_install_property (object_class,
             PROP_LEVEL,
             g_param_spec_double ("level",

diff --git a/src/hildon-volumebar.c b/src/hildon-volumebar.c
index 8a38127..e72fe00 100644 (file)
--- a/src/hildon-volumebar.c
+++ b/src/hildon-volumebar.c
@@ -114,6 +114,13 @@ enum {
 
 static guint                                    signals [LAST_SIGNAL] = { 0 };
 
+/**
+ * hildon_volumebar_get_type:
+ *
+ * Initializes and returns the type of a hildon volumebar.
+ *
+ * @Returns: GType of #HildonVolumebar
+ */
 GType G_GNUC_CONST 
 hildon_volumebar_get_type                       (void)
 {
@@ -191,7 +198,11 @@ hildon_volumebar_class_init                     (HildonVolumebarClass *volumebar
    gobject_class->set_property          = hildon_volumebar_set_property;
    gobject_class->get_property          = hildon_volumebar_get_property; 
 
-   /*This kind of property could be usefull in the gtkcontainer*/
+   /**
+    * HildonVolumebar:can-focus:
+    *
+    * The widget focusability.
+    */
    g_object_class_install_property (gobject_class,
            PROP_HILDON_FOCUSABLE, 
            g_param_spec_boolean ("can-focus",
@@ -200,6 +211,11 @@ hildon_volumebar_class_init                     (HildonVolumebarClass *volumebar
                TRUE,
                G_PARAM_CONSTRUCT | G_PARAM_READWRITE));
 
+   /**
+    * HildonVolumebar:has-mute:
+    *
+    * Whether the mute button is visibile.
+    */
    g_object_class_install_property (gobject_class,
            PROP_HILDON_HAS_MUTE, 
            g_param_spec_boolean ("has_mute",
@@ -208,6 +224,11 @@ hildon_volumebar_class_init                     (HildonVolumebarClass *volumebar
                TRUE,
                G_PARAM_CONSTRUCT | G_PARAM_READWRITE));
 
+   /**
+    * HildonVolumebar:level:
+    *
+    * Current volume level.
+    */
    g_object_class_install_property (gobject_class,
            PROP_HILDON_LEVEL,
            g_param_spec_double ("level",
@@ -218,6 +239,11 @@ hildon_volumebar_class_init                     (HildonVolumebarClass *volumebar
                50.0,
                G_PARAM_READWRITE));
 
+   /**
+    * HildonVolumebar:can-focus:
+    *
+    * Whether volume is muted.
+    */
    g_object_class_install_property (gobject_class,
            PROP_HILDON_MUTE,
            g_param_spec_boolean ("mute",
@@ -661,9 +687,9 @@ hildon_volumebar_key_press                      (GtkWidget *widget,
 void G_GNUC_INTERNAL
 hildon_volumebar_mute_toggled                   (HildonVolumebar * self)
 {
-    g_return_if_fail(HILDON_IS_VOLUMEBAR(self));
+    g_return_if_fail (HILDON_IS_VOLUMEBAR (self));
     /* FIXME Emit by id */
-    g_signal_emit_by_name(self, "mute_toggled");
+    g_signal_emit_by_name (self, "mute_toggled");
 }
 
 void G_GNUC_INTERNAL 
@@ -672,5 +698,5 @@ hildon_volumebar_level_change                   (HildonVolumebar *self)
     g_return_if_fail (HILDON_IS_VOLUMEBAR (self));
 
     /* FIXME Use numerical val, id */
-    g_signal_emit_by_name (GTK_WIDGET(self), "level_changed");
+    g_signal_emit_by_name (GTK_WIDGET (self), "level_changed");
 }

diff --git a/src/hildon-vvolumebar.c b/src/hildon-vvolumebar.c
index 9bc18bc..8145781 100644 (file)
--- a/src/hildon-vvolumebar.c
+++ b/src/hildon-vvolumebar.c
@@ -80,6 +80,13 @@ static void
 hildon_vvolumebar_size_allocate                 (GtkWidget * widget,
                                                  GtkAllocation * allocation);
 
+/**
+ * hildon_vvolumebar_get_type:
+ *
+ * Initializes and returns the type of a hildon vvolumebar.
+ *
+ * @Returns: GType of #HildonVVolumebar
+ */
 GType G_GNUC_CONST
 hildon_vvolumebar_get_type                      (void)
 {

diff --git a/src/hildon-weekday-picker.c b/src/hildon-weekday-picker.c
index e8099a1..d588efe 100644 (file)
--- a/src/hildon-weekday-picker.c
+++ b/src/hildon-weekday-picker.c
@@ -97,6 +97,13 @@ enum
 
 static guint                                    signals [LAST_SIGNAL] = { 0 } ;
 
+/**
+ * hildon_weekday_picker_get_type:
+ *
+ * Initializes and returns the type of a hildon weekday picker.
+ *
+ * @Returns: GType of #HildonWeekdayPicker
+ */
 GType G_GNUC_CONST
 hildon_weekday_picker_get_type                  (void)
 {

diff --git a/src/hildon-window.c b/src/hildon-window.c
index bde1aa8..da6688f 100644 (file)
--- a/src/hildon-window.c
+++ b/src/hildon-window.c
@@ -22,6 +22,17 @@
  *
  */
 
+/**
+ * SECTION:hildon-window
+ * @short_description: A basic container for other hildon widgets.
+ *
+ * A single #HildonProgram can contain many #HildonWindows. 
+ * HildonWindow is a customized version of GtkWindow that handles
+ * automatically some taks of the Hildon UI. A typicall hildon application
+ * should contain at least one #HildonWindow.
+ *
+ */
+
 #include                                        "hildon-window.h"
 #include                                        <memory.h>
 #include                                        <string.h>
@@ -184,6 +195,13 @@ enum
     MAX_WIN_MESSAGES
 };
 
+/**
+ * hildon_window_get_type:
+ *
+ * Initializes and returns the type of a hildon window.
+ *
+ * @Returns: GType of #HildonWindow
+ */
 GType G_GNUC_CONST
 hildon_window_get_type                          (void)
 {
@@ -244,6 +262,12 @@ hildon_window_class_init                        (HildonWindowClass * window_clas
             sizeof (struct _HildonWindowPrivate));
 
     /* Install properties */
+    
+    /**
+     * HildonWindow:is-topmost:
+     *
+     * Whether the window is currently activated by the window manager.
+     */
     g_object_class_install_property (object_class, PROP_IS_TOPMOST,
             g_param_spec_boolean ("is-topmost",
                 "Is top-most",
@@ -1551,7 +1575,6 @@ hildon_window_escape_timeout                    (gpointer data)
     return FALSE;
 }
 
-
 /**
  * hildon_window_new: 
  * 

diff --git a/src/hildon-wizard-dialog.c b/src/hildon-wizard-dialog.c
index a5c3f1b..b721e37 100644 (file)
--- a/src/hildon-wizard-dialog.c
+++ b/src/hildon-wizard-dialog.c
@@ -99,6 +99,13 @@ enum
     PROP_AUTOTITLE
 };
 
+/**
+ * hildon_wizard_dialog_get_type:
+ *
+ * Initializes and returns the type of a hildon wizard dialog.
+ *
+ * @Returns: GType of #HildonWzardDialog
+ */
 GType G_GNUC_CONST
 hildon_wizard_dialog_get_type                   (void)
 {