changeset 18304:38ecbc8a70bd

Start filling in the doxygen-help skeleton.

--- a/finch/libgnt/gntbox.h	Wed Jun 27 04:15:36 2007 +0000
+++ b/finch/libgnt/gntbox.h	Wed Jun 27 06:32:56 2007 +0000
@@ -88,9 +88,8 @@
 G_BEGIN_DECLS
 
 /**
- * 
- *
- * @return
+ * The GType for GntBox.
+ * @return The GType.
  */
 GType gnt_box_get_gtype(void);
 
@@ -98,98 +97,110 @@
 #define gnt_hbox_new(homo) gnt_box_new(homo, FALSE)
 
 /**
- * 
- * @param homo
- * @param vert
+ * Create a new GntBox.
  *
- * @return
+ * @param homo  If @c TRUE, all the widgets in it will have the same width (or height)
+ * @param vert  Whether the widgets in it should be stacked vertically (if @c TRUE)
+ *              or horizontally (if @c FALSE).
+ *
+ * @return The new GntBox.
  */
 GntWidget * gnt_box_new(gboolean homo, gboolean vert);
 
 /**
- * 
- * @param box
- * @param widget
+ * Add a widget in the box.
+ *
+ * @param box     The box
+ * @param widget  The widget to add
  */
 void gnt_box_add_widget(GntBox *box, GntWidget *widget);
 
 /**
- * 
- * @param box
- * @param title
+ * Set a title for the box.
+ *
+ * @param box    The box
+ * @param title	 The title to set
  */
 void gnt_box_set_title(GntBox *box, const char *title);
 
 /**
- * 
- * @param box
- * @param pad
+ * Set the padding to use between the widgets in the box.
+ *
+ * @param box The box
+ * @param pad The padding to use
  */
 void gnt_box_set_pad(GntBox *box, int pad);
 
 /**
- * 
- * @param box
- * @param set
+ * Set whether it's a toplevel box (ie, a window) or not. If a box is toplevel,
+ * then it will show borders, the title (if set) and shadow (if enabled in
+ * @e .gntrc)
+ *
+ * @param box The box
+ * @param set @c TRUE if it's a toplevel box, @c FALSE otherwise.
  */
 void gnt_box_set_toplevel(GntBox *box, gboolean set);
 
 /**
- * 
- * @param box
+ * Reposition and refresh the widgets in the box.
+ *
+ * @param box The box
  */
 void gnt_box_sync_children(GntBox *box);
 
 /**
- * 
- * @param box
- * @param alignment
+ * Set the alignment for the widgets in the box.
+ *
+ * @param box       The box
+ * @param alignment The alignment to use
  */
 void gnt_box_set_alignment(GntBox *box, GntAlignment alignment);
 
 /**
- * 
- * @param box
- * @param widget
+ * Remove a widget from the box. Calling this does NOT destroy the removed widget.
+ *
+ * @param box       The box
+ * @param widget    The widget to remove
  */
 void gnt_box_remove(GntBox *box, GntWidget *widget);
 
- /* XXX: does NOT destroy widget */
-
 /**
- * 
- * @param box
+ * Remove all widgets from the box. This DOES destroy all widgets in the box.
+ *
+ * @param box The box
  */
 void gnt_box_remove_all(GntBox *box);
 
-      /* Removes AND destroys all the widgets in it */
-
 /**
- * 
- * @param box
+ * Readjust the size of each child widget, reposition the child widgets and
+ * recalculate the size of the box.
+ *
+ * @param box  The box
  */
 void gnt_box_readjust(GntBox *box);
 
 /**
- * 
- * @param box
- * @param fill
+ * Set whether the widgets in the box should fill the empty spaces.
+ *
+ * @param box   The box
+ * @param fill  Whether the child widgets should fill the empty space
  */
 void gnt_box_set_fill(GntBox *box, gboolean fill);
 
 /**
- * 
- * @param box
- * @param dir
+ * Move the focus from one widget to the other.
+ *
+ * @param box The box
+ * @param dir The direction. If it's 1, then the focus is moved forwards, if it's
+ *            -1, the focus is moved backwards.
  */
 void gnt_box_move_focus(GntBox *box, int dir);
 
-  /* +1 to move forward, -1 for backward */
-
 /**
- * 
- * @param box
- * @param widget
+ * Give focus to a specific child widget.
+ *
+ * @param box       The box
+ * @param widget    The child widget to give focus
  */
 void gnt_box_give_focus_to_child(GntBox *box, GntWidget *widget);
 

--- a/finch/libgnt/gntutils.h	Wed Jun 27 04:15:36 2007 +0000
+++ b/finch/libgnt/gntutils.h	Wed Jun 27 06:32:56 2007 +0000
@@ -32,87 +32,101 @@
 typedef gpointer (*GDupFunc)(gconstpointer data);
 
 /**
- * 
- * @param text
- * @param width
- * @param height
+ * Compute the width and height required to view the text on the screen.
+ *
+ * @param text     The text to be displayed.
+ * @param width    The width required is set here, if not @c NULL.
+ * @param height   The height required is set here, if not @c NULL.
  */
 void gnt_util_get_text_bound(const char *text, int *width, int *height);
 
-/* excluding *end */
 /**
- * 
- * @param start
- * @param end
+ * Get the onscreen width of a string, or a substring.
  *
- * @return
+ * @param start  The beginning of the string.
+ * @param end    The end of the string. The width returned is the width
+ *               upto (but not including) end. If end is NULL, then start
+ *               is considered as a @c NULL-terminated string.
+ *
+ * @return       The on-screen width of the string.
  */
 int gnt_util_onscreen_width(const char *start, const char *end);
 
+/**
+ * Computes and returns the string after a specific number of onscreen characters.
+ *
+ * @param str  The string.
+ * @param len  The length to consider. If non-positive, the entire screenlength is used.
+ * @param w    The actual width of the string upto the returned offset, if not @c NULL.
+ *
+ * @return     The string after len offset.
+ */
 const char *gnt_util_onscreen_width_to_pointer(const char *str, int len, int *w);
 
-/* Inserts newlines in 'string' where necessary so that its onscreen width is
+/**
+ * Inserts newlines in 'string' where necessary so that its onscreen width is 
  * no more than 'maxw'.
- * 'maxw' can be <= 0, in which case the maximum screen width is considered.
  *
- * Returns a newly allocated string.
- */
-/**
- * 
- * @param string
- * @param maxw
+ * @param string  The string.
+ * @param maxw    The width that the string should fit into. If maxw is <= 0,
+ *                then the available maximum width is used.
  *
- * @return
+ * @return  A newly allocated string that needs to be freed by the caller.
  */
 char * gnt_util_onscreen_fit_string(const char *string, int maxw);
 
 /**
- * 
- * @param src
- * @param hash
- * @param equal
- * @param key_d
- * @param value_d
- * @param key_dup
- * @param value_dup
+ * Duplicate the contents of a hastable.
  *
- * @return
+ * @param src         The source hashtable.
+ * @param hash        The hash-function to use.
+ * @param equal       The hash-equal function to use.
+ * @param key_d       The key-destroy function to use.
+ * @param value_d     The value-destroy function to use.
+ * @param key_dup     The function to use to duplicate the key.
+ * @param value_dup   The function to use to duplicate the value.
+ *
+ * @return    The new hashtable.
  */
 GHashTable * g_hash_table_duplicate(GHashTable *src, GHashFunc hash, GEqualFunc equal, GDestroyNotify key_d, GDestroyNotify value_d, GDupFunc key_dup, GDupFunc value_dup);
 
 /**
  * To be used with g_signal_new. Look in the key_pressed signal-definition in
  * gntwidget.c for usage.
- */
-/**
- * 
- * @param ihint
- * @param return_accu
- * @param handler_return
- * @param dummy
  *
- * @return
+ * @param ihint           NA
+ * @param return_accu     NA
+ * @param handler_return  NA
+ * @param dummy           NA
+ *
+ * @return  NA
  */
 gboolean gnt_boolean_handled_accumulator(GSignalInvocationHint *ihint, GValue *return_accu, const GValue *handler_return, gpointer dummy);
 
 /**
- * Returns a GntTree populated with "key" -> "binding" for the widget.
- */
-/**
+ * Get a helpful display about the bindings of a widget.
  * 
- * @param widget
+ * @param widget The widget to get bindings for.
  *
- * @return
+ * @return Returns a GntTree populated with "key" -> "binding" for the widget.
  */
 GntWidget * gnt_widget_bindings_view(GntWidget *widget);
 
 /**
- * Parse widgets from 'string'.
- */
-/**
+ * Parse widgets from an XML description. For example,
+ *
+ * @code
+ * GntWidget *win, *button;
+ * gnt_util_parse_widgets("\
+ *      <vwindow id='0' fill='0' align='2'>     \
+ *          <label>This is a test</label>       \
+ *          <button id='1'>OK</button>          \
+ *      </vwindow>",
+ *   2, &win, &button);
+ * @endcode
  * 
- * @param string
- * @param num
+ * @param string  The XML string.
+ * @param num     The number of widgets to return, followed by 'num' GntWidget **
  */
 void gnt_util_parse_widgets(const char *string, int num, ...);