Cleaning up the documentation.

diff --git a/ChangeLog.2 b/ChangeLog.2
index a8e586f..456fa6f 100644 (file)
--- a/ChangeLog.2
+++ b/ChangeLog.2
@@ -1,3 +1,13 @@
+2007-01-24  Michael Dominic Kostrzewa  <michael.kostrzewa@nokia.com> 
+
+       * src/hildon-get-password-dialog.c:
+       * src/hildon-helper.c:
+       * src/hildon-hvolumebar.c:
+       * src/hildon-login-dialog.c:
+       * src/hildon-note.c:
+       * src/hildon-note.h:
+       * src/hildon-number-editor.c: Cleaning up the documentation.
+
 2007-01-23  Michael Dominic Kostrzewa  <michael.kostrzewa@nokia.com> 
 
        * src/hildon-defines.h: Removing accidentaly left function prototypes.

diff --git a/src/hildon-get-password-dialog.c b/src/hildon-get-password-dialog.c
index b5254b2..0ba4de6 100644 (file)
--- a/src/hildon-get-password-dialog.c
+++ b/src/hildon-get-password-dialog.c
@@ -232,6 +232,12 @@ hildon_get_password_dialog_class_init           (HildonGetPasswordDialogClass *c
     object_class->get_property = hildon_get_password_get_property;
 
     /* Install new properties */
+    
+    /**
+     * HildonGetPasswordDialog:message:
+     *
+     * Optional message displayed to the user.
+     */
     g_object_class_install_property 
         (object_class, 
          PROP_MESSAGE, 
@@ -241,6 +247,11 @@ hildon_get_password_dialog_class_init           (HildonGetPasswordDialogClass *c
              NULL,
              G_PARAM_READWRITE));
 
+    /**
+     * HildonGetPasswordDialog:password:
+     *
+     * Password field contents.
+     */
     g_object_class_install_property
         (object_class, 
          PROP_PASSWORD,
@@ -250,15 +261,25 @@ hildon_get_password_dialog_class_init           (HildonGetPasswordDialogClass *c
              "DEFAULT",
              G_PARAM_READWRITE));
 
+    /**
+     * HildonGetPasswordDialog:numbers-only:
+     *
+     * If the password entry field is operating in numbers-only mode.
+     */
     g_object_class_install_property
         (object_class, 
          PROP_NUMBERS_ONLY,
-         g_param_spec_boolean ("numbers_only",
+         g_param_spec_boolean ("numbers-only",
              "NumbersOnly",
              "Set entry to accept only numeric values",
              FALSE,
              G_PARAM_READWRITE));
 
+    /**
+     * HildonGetPasswordDialog:caption-label:
+     *
+     * Caption label.
+     */
     g_object_class_install_property
         (object_class, 
          PROP_CAPTION_LABEL,
@@ -267,7 +288,12 @@ hildon_get_password_dialog_class_init           (HildonGetPasswordDialogClass *c
              "The text to be set as the caption label",
              NULL,
              G_PARAM_READWRITE));
-
+    
+    /**
+     * HildonGetPasswordDialog:max-characters:
+     *
+     * Maximum characters than can be entered.
+     */
     g_object_class_install_property
         (object_class, 
          PROP_MAX_CHARS,
@@ -280,6 +306,11 @@ hildon_get_password_dialog_class_init           (HildonGetPasswordDialogClass *c
              0,
              G_PARAM_READWRITE));
 
+    /**
+     * HildonGetPasswordDialog:get-old:
+     *
+     * If the dialog is used to retrieve an old password or set a new one.
+     */
     g_object_class_install_property
         (object_class,
          PROP_GET_OLD,
@@ -463,7 +494,7 @@ hildon_get_password_dialog_new_with_default     (GtkWindow *parent,
  * hildon_get_password_dialog_get_password:
  * @dialog: pointer to HildonSetPasswordDialog
  * 
- * Gets the currently entered password.
+ * Gets the currently entered password. The string should not be freed.
  *
  * Returns: current password entered by the user.
  */
@@ -491,7 +522,7 @@ hildon_get_password_dialog_get_password         (HildonGetPasswordDialog *dialog
  * @dialog: the dialog
  * @message: a custom message or some other descriptive text to be set
  * 
- * Sets the optional descriptive text.
+ * Sets the optional descriptive text displayed at the top of the dialog.
  */
 void 
 hildon_get_password_dialog_set_message          (HildonGetPasswordDialog *dialog, 

diff --git a/src/hildon-helper.c b/src/hildon-helper.c
index 1963666..c188cf3 100644 (file)
--- a/src/hildon-helper.c
+++ b/src/hildon-helper.c
@@ -157,7 +157,7 @@ hildon_logical_data_free                        (HildonLogicalData *ld)
  *
  * Checks if the given button event is a finger event.
  * 
- * return value : TRUE if the event is a button event.
+ * return value : TRUE if the event is a finger event.
  **/
 gboolean 
 hildon_helper_event_button_is_finger (GdkEventButton *event)
@@ -186,11 +186,11 @@ hildon_helper_event_button_is_finger (GdkEventButton *event)
  * @widget : a @gtkwidget to assign this logical font for.
  * @logicalfontname : a gchar* with the logical font name to assign to the widget.
  * 
- * this function assigns a defined logical font to the @widget and all its child widgets.
+ * This function assigns a defined logical font to the @widget and all its child widgets.
  * it also connects to the "style_set" signal which will retrieve & assign the new font 
  * for the given logical name each time the theme is changed.
- * the returned signal id can be used to disconnect the signal. 
- * the previous signal (obtained by calling this function) is disconnected 
+ * The returned signal id can be used to disconnect the signal. 
+ * When calling multiple times the previous signal (obtained by calling this function) is disconnected 
  * automatically and should not be used. 
  * 
  * return value : the signal id that is triggered every time theme is changed. 0 if font set failed.
@@ -240,7 +240,7 @@ hildon_helper_set_logical_font                  (GtkWidget *widget,
  * It also connects to the "style_set" signal which will retrieve & assign the new color 
  * for the given logical name each time the theme is changed.
  * The returned signal id can be used to disconnect the signal.
- * The previous signal (obtained by calling this function) is disconnected 
+ * When calling multiple times the previous signal (obtained by calling this function) is disconnected 
  * automatically and should not be used. 
  * 
  * Example : If the style you want to modify is bg[NORMAL] then set rcflags to GTK_RC_BG and state to GTK_STATE_NORMAL.

diff --git a/src/hildon-hvolumebar.c b/src/hildon-hvolumebar.c
index 6de1581..67a2a8d 100644 (file)
--- a/src/hildon-hvolumebar.c
+++ b/src/hildon-hvolumebar.c
@@ -95,7 +95,13 @@ hildon_hvolumebar_size_allocate                 (GtkWidget *widget,
 static void 
 hildon_hvolumebar_map                           (GtkWidget *widget);
 
-
+/**
+ * hildon_hvolumebar_get_type:
+ *
+ * Returns GType for HildonHVolumebar.
+ *
+ * Returns: HildonHVolumebar type
+ */
 GType G_GNUC_CONST
 hildon_hvolumebar_get_type                      (void)
 {
@@ -211,7 +217,6 @@ hildon_hvolumebar_expose                        (GtkWidget * widget,
                 widget->allocation.width,
                 widget->allocation.height);
 
-
         /* The contents of the widget can paint themselves */
         /* FIXME Not sure if this is even needed here */
         (*GTK_WIDGET_CLASS(parent_class)->expose_event) (widget, event);

diff --git a/src/hildon-login-dialog.c b/src/hildon-login-dialog.c
index 26920f0..3d8a404 100644 (file)
--- a/src/hildon-login-dialog.c
+++ b/src/hildon-login-dialog.c
@@ -90,6 +90,13 @@ hildon_login_dialog_get_property                (GObject *object,
 
 static GtkDialogClass*                          parent_class;
 
+/**
+ * hildon_login_dialog_get_type:
+ *
+ * Returns GType for HildonLoginDialog.
+ *
+ * Returns: HildonLoginDialog type
+ */
 GType G_GNUC_CONST
 hildon_login_dialog_get_type                    (void)
 {
@@ -196,6 +203,12 @@ hildon_login_dialog_class_init                  (HildonLoginDialogClass *class)
     object_class->get_property = hildon_login_dialog_get_property;
 
     /* Install new properties */
+
+    /**
+     * HildonLoginDialog:message:
+     *
+     * Optional message displayed to the user.
+     */
     g_object_class_install_property (object_class, 
             PROP_MESSAGE, 
             g_param_spec_string ("message",
@@ -204,6 +217,11 @@ hildon_login_dialog_class_init                  (HildonLoginDialogClass *class)
                 NULL,
                 G_PARAM_READWRITE));
 
+    /**
+     * HildonLoginDialog:username:
+     *
+     * Contents of the username field.
+     */
     g_object_class_install_property (object_class,
             PROP_USERNAME, 
             g_param_spec_string ("username",
@@ -211,7 +229,12 @@ hildon_login_dialog_class_init                  (HildonLoginDialogClass *class)
                 "Username field",
                 "DEFAULT",
                 G_PARAM_READWRITE));
-
+    
+    /**
+     * HildonLoginDialog:password:
+     *
+     * Contents of the password field.
+     */
     g_object_class_install_property (object_class, 
             PROP_PASSWORD,
             g_param_spec_string ("password",
@@ -381,7 +404,8 @@ hildon_login_dialog_get_password                (HildonLoginDialog *dialog)
  * @dialog: the dialog
  * @msg: the message or some other descriptive text to be set
  * 
- * sets the optional descriptive text
+ * Sets the optional descriptive text that is displayed on the top 
+ * of the dialog. 
  */
 void 
 hildon_login_dialog_set_message                 (HildonLoginDialog *dialog, 

diff --git a/src/hildon-note.c b/src/hildon-note.c
index 023a6c4..d8107ce 100644 (file)
--- a/src/hildon-note.c
+++ b/src/hildon-note.c
@@ -214,6 +214,13 @@ hildon_note_get_property                        (GObject *object,
     }
 }
 
+/**
+ * hildon_note_get_type:
+ *
+ * Returns GType for HildonNote.
+ *
+ * Returns: HildonNote type
+ */
 GType G_GNUC_CONST
 hildon_note_get_type                            (void)
 {
@@ -259,14 +266,14 @@ hildon_note_class_init                          (HildonNoteClass *class)
             g_param_spec_enum ("note_type",
                 "note type",
                 "The type of the note dialog",
-                hildon_note_type_get_type(),
+                hildon_note_get_type (),
                 HILDON_NOTE_CONFIRMATION_TYPE,
                 G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
 
     /**
      * HildonNote:description:
      *
-     * Description for note.
+     * Description for the note.
      */
     g_object_class_install_property (object_class,
             PROP_HILDON_NOTE_DESCRIPTION,
@@ -279,7 +286,7 @@ hildon_note_class_init                          (HildonNoteClass *class)
     /**
      * HildonNote:icon:
      *
-     * Icon for note.
+     * Icon for the note.
      */
     g_object_class_install_property (object_class,
             PROP_HILDON_NOTE_ICON,
@@ -292,7 +299,7 @@ hildon_note_class_init                          (HildonNoteClass *class)
     /**
      * HildonNote:stock-icon:
      *
-     * Stock icon for note.
+     * Stock icon name for the note.
      */
     g_object_class_install_property (object_class,
             PROP_HILDON_NOTE_STOCK_ICON,
@@ -305,7 +312,7 @@ hildon_note_class_init                          (HildonNoteClass *class)
     /**
      * HildonNote:progressbar:
      *
-     * Progressbar for note.
+     * Progressbar for the note (if any).
      */
     g_object_class_install_property (object_class,
             PROP_HILDON_NOTE_PROGRESSBAR,

diff --git a/src/hildon-note.h b/src/hildon-note.h
index 38e3a2c..b6302d5 100644 (file)
--- a/src/hildon-note.h
+++ b/src/hildon-note.h
@@ -50,15 +50,6 @@ typedef struct                                  _HildonNote HildonNote;
 
 typedef struct                                  _HildonNoteClass HildonNoteClass;
 
-typedef enum
-{
-    HILDON_NOTE_CONFIRMATION_TYPE = 0,
-    HILDON_NOTE_CONFIRMATION_BUTTON_TYPE,
-    HILDON_NOTE_INFORMATION_TYPE,
-    HILDON_NOTE_INFORMATION_THEME_TYPE,
-    HILDON_NOTE_PROGRESSBAR_TYPE
-}                                               HildonNoteType;
-
 struct                                          _HildonNote 
 {
     GtkDialog parent;
@@ -109,6 +100,15 @@ hildon_note_set_button_texts                    (HildonNote *note,
                                                  const gchar *text_ok,
                                                  const gchar *text_cancel);
 
+typedef enum
+{
+    HILDON_NOTE_CONFIRMATION_TYPE = 0,
+    HILDON_NOTE_CONFIRMATION_BUTTON_TYPE,
+    HILDON_NOTE_INFORMATION_TYPE,
+    HILDON_NOTE_INFORMATION_THEME_TYPE,
+    HILDON_NOTE_PROGRESSBAR_TYPE
+}                                               HildonNoteType;
+
 G_END_DECLS
 
 #endif                                          /* __HILDON_NOTE_H__ */

diff --git a/src/hildon-number-editor.c b/src/hildon-number-editor.c
index 3613040..0095ef0 100644 (file)
--- a/src/hildon-number-editor.c
+++ b/src/hildon-number-editor.c
@@ -166,6 +166,13 @@ static GtkContainerClass*                       parent_class;
 
 static guint                                    HildonNumberEditor_signal[LAST_SIGNAL] = {0};
 
+/**
+ * hildon_number_editor_get_type:
+ *
+ * Returns GType for HildonNumberEditor.
+ *
+ * Returns: HildonNumberEditor type
+ */
 GType G_GNUC_CONST
 hildon_number_editor_get_type                   (void)
 {
@@ -218,6 +225,11 @@ hildon_number_editor_class_init                 (HildonNumberEditorClass *editor
     gobject_class->set_property             = hildon_number_editor_set_property;
     gobject_class->get_property             = hildon_number_editor_get_property;
 
+    /**
+     * HildonNumberEditor:value:
+     *
+     * The current value of the number editor.
+     */
     g_object_class_install_property (gobject_class, PROP_VALUE,
             g_param_spec_int ("value",
                 "Value",
@@ -832,7 +844,6 @@ hildon_number_editor_range_error                (HildonNumberEditor *editor,
     return TRUE;
 }
 
-
 /**
  * hildon_number_editor_new:
  * @min: minimum accepted value