Update comments, rename Widget to ThemeWidget.

7 files changed, 291 insertions, 15 deletions

diff --git a/include/theme.h b/include/theme.h
index e96636d2..1eaf4718 100644
--- a/include/theme.h
+++ b/include/theme.h
@@ -2,27 +2,48 @@
 #define THEME_H
 #include <glib.h>
 #include <cairo.h>
+
+/**
+ * Distance unit type.
+ */
 typedef enum {
+    /** PixelWidth in pixels. */
     PW_PX,
+    /** PixelWidth in EM. */
     PW_EM,
-
 } PixelWidth;
 
+/**
+ * Structure representing a distance.
+ */
 typedef struct {
+    /** Distance */
     double     distance;
+    /** Unit type of the distance */
     PixelWidth type;
 } Distance;
 
+/**
+ * Type of property
+ */
 typedef enum {
+    /** Integer */
     P_INTEGER,
+    /** Double */
     P_DOUBLE,
+    /** String */
     P_STRING,
+    /** Boolean */
     P_BOOLEAN,
+    /** Color */
     P_COLOR,
-    // Used in padding.
+    /** Padding */
     P_PADDING,
 } PropertyType;
 
+/**
+ * Represent the color in theme.
+ */
 typedef struct
 {
     /** red channel */
@@ -35,6 +56,9 @@ typedef struct
     double alpha;
 } ThemeColor;
 
+/**
+ * Padding
+ */
 typedef struct
 {
     Distance top;
@@ -55,45 +79,189 @@ typedef struct {
         Padding    padding;
     } value;
 } Property;
-
-typedef struct _Widget {
+/**
+ * ThemeWidget.
+ */
+typedef struct ThemeWidget {
     int set;
     char *name;
 
     unsigned int num_widgets;
-    struct _Widget **widgets;
+    struct ThemeWidget **widgets;
 
     GHashTable *properties;
 
-    struct _Widget *parent;
-} Widget;
-
+    struct ThemeWidget *parent;
+} ThemeWidget;
 
-extern Widget *rofi_theme;
 
-Widget *rofi_theme_find_or_create_class ( Widget *base, const char *class );
+/**
+ * Global pointer to the current active theme.
+ */
+extern ThemeWidget *rofi_theme;
 
+/**
+ * @param base Handle to the current level in the theme.
+ * @param class Name of the new element.
+ *
+ * Create a new element in the theme structure.
+ *
+ * @returns handle to the new entry.
+ */
+ThemeWidget *rofi_theme_find_or_create_class ( ThemeWidget *base, const char *class );
 
-void rofi_theme_print ( Widget *widget );
+/**
+ * @param widget The widget handle.
+ *
+ * Print out the widget to the commandline.
+ */
+void rofi_theme_print ( ThemeWidget *widget );
 
+/**
+ * @param type The type of the property to create.
+ *
+ * Create a theme property of type.
+ *
+ * @returns a new property.
+ */
 Property *rofi_theme_property_create ( PropertyType type );
+
+/**
+ * @param p The property to free.
+ *
+ * Free the content of the property.
+ */
 void rofi_theme_property_free ( Property *p );
-void rofi_theme_free ( Widget * );
+
+/**
+ * @param wid
+ *
+ * Free the widget and alll children.
+ */
+void rofi_theme_free ( ThemeWidget * );
+
+/**
+ * @param file filename to parse. 
+ *
+ * Parse the input theme file.
+ */
 void rofi_theme_parse_file ( const char *file );
-void rofi_theme_widget_add_properties ( Widget *widget, GHashTable *table );
+
+/**
+ * @param widget The widget handle.
+ * @param table HashTable containing properties set.
+ *
+ * Merge properties with widgets current property.
+ */
+void rofi_theme_widget_add_properties ( ThemeWidget *widget, GHashTable *table );
 
 /**
  * Public API
  */
 
+/**
+ * @param wclass   The widget class
+ * @param name     The name class
+ * @param state    The widget current state
+ * @param property The property to query.
+ * @param def      The default value.
+ *
+ * Obtain the distance of the widget.
+ *
+ * @returns The distance value of this property for this widget. 
+ */
 Distance rofi_theme_get_distance ( const char *wclass, const char  *name, const char *state, const char *property, int def );
+
+/**
+ * @param wclass   The widget class
+ * @param name     The name class
+ * @param state    The widget current state
+ * @param property The property to query.
+ * @param def      The default value.
+ *
+ * Obtain the integer of the widget.
+ *
+ * @returns The integer value of this property for this widget. 
+ */
 int rofi_theme_get_integer   ( const char *wclass,  const char *name, const char *state,  const char *property, int def );
+
+/**
+ * @param wclass   The widget class
+ * @param name     The name class
+ * @param state    The widget current state
+ * @param property The property to query.
+ * @param def      The default value.
+ *
+ * Obtain the boolean of the widget.
+ *
+ * @returns The boolean value of this property for this widget. 
+ */
 int rofi_theme_get_boolean   ( const char *wclass,  const char *name, const char *state,  const char *property, int def );
+
+/**
+ * @param wclass   The widget class
+ * @param name     The name class
+ * @param state    The widget current state
+ * @param property The property to query.
+ * @param def      The default value.
+ *
+ * Obtain the string of the widget.
+ *
+ * @returns The string value of this property for this widget. 
+ */
 char *rofi_theme_get_string  ( const char *wclass,  const char *name, const char *state,  const char *property, char *def );
+
+/**
+ * @param wclass   The widget class
+ * @param name     The name class
+ * @param state    The widget current state
+ * @param property The property to query.
+ * @param def      The default value.
+ *
+ * Obtain the padding of the widget.
+ *
+ * @returns The double value of this property for this widget. 
+ */
 double rofi_theme_get_double ( const char *wclass,  const char *name, const char *state,  const char *property, double def );
+
+/**
+ * @param wclass   The widget class
+ * @param name     The name class
+ * @param state    The widget current state
+ * @param property The property to query.
+ * @param def      The default value.
+ *
+ * Obtain the color of the widget.
+ *
+ * @returns The color value of this property for this widget. 
+ */
 void rofi_theme_get_color ( const char *wclass, const char  *name, const char *state, const char *property, cairo_t *d);
+
+/**
+ * @param wclass   The widget class
+ * @param name     The name class
+ * @param state    The widget current state
+ * @param property The property to query.
+ * @param def      The default value.
+ *
+ * Obtain the padding of the widget.
+ *
+ * @returns The padding of this property for this widget. 
+ */
 Padding rofi_theme_get_padding ( const char *wclass, const char  *name, const char *state, const char *property, Padding pad );
 
+/**
+ * @param d The distance handle.
+ *
+ * Convert Distance into pixels.
+ * @returns the number of pixels this distance represents.
+ */
 int distance_get_pixel ( Distance d );
+
+#ifdef THEME_CONVERTER
+/**
+ * Function to convert old theme into new theme format.
+ */
 void rofi_theme_convert_old_theme ( void );
 #endif
+#endif
diff --git a/include/view-internal.h b/include/view-internal.h
index f2f000bb..96dffdb7 100644
--- a/include/view-internal.h
+++ b/include/view-internal.h
@@ -24,7 +24,7 @@ struct RofiViewState
 
     /** Flag indicating if view needs to be refiltered. */
     int              refilter;
-
+    /** Widget representing the main window. */
     window           *main_window;
     /** Main #box widget holding different elements. */
     box              *main_box;
diff --git a/include/widgets/scrollbar.h b/include/widgets/scrollbar.h
index 0abfa521..4efbaaa5 100644
--- a/include/widgets/scrollbar.h
+++ b/include/widgets/scrollbar.h
@@ -63,6 +63,12 @@ void scrollbar_set_max_value ( scrollbar *sb, unsigned int max );
  */
 unsigned int scrollbar_clicked ( const scrollbar *sb, int y );
 
+/**
+ * @param sb scrollbar object
+ * @param width width of the scrollbar
+ *
+ * Set the width of the scrollbar handle.
+ */
 void scrollbar_set_width ( scrollbar *sb, int width );
 /*@}*/
 #endif // ROFI_SCROLLBAR_H
diff --git a/include/widgets/textbox.h b/include/widgets/textbox.h
index 14484a25..1b6a4152 100644
--- a/include/widgets/textbox.h
+++ b/include/widgets/textbox.h
@@ -196,6 +196,12 @@ int textbox_get_font_width ( const textbox *tb );
  * @returns the width of a character in pixels.
  */
 double textbox_get_estimated_char_width ( void );
+
+/**
+ * Estimate the height of a character.
+ *
+ * @returns the height of a character in pixels.
+ */
 double textbox_get_estimated_char_height ( void  );
 
 /**
@@ -255,6 +261,5 @@ PangoAttrList *textbox_get_pango_attributes ( textbox *tb );
  * @returns the visible text.
  */
 const char *textbox_get_visible_text ( const textbox *tb );
-int distance_get_pixel ( Distance d );
 /*@}*/
 #endif //ROFI_TEXTBOX_H
diff --git a/include/widgets/widget-internal.h b/include/widgets/widget-internal.h
index 0eb1ef54..5151c8b1 100644
--- a/include/widgets/widget-internal.h
+++ b/include/widgets/widget-internal.h
@@ -57,15 +57,90 @@ struct _widget
     const char *state;
 };
 
+/**
+ * @param widget The widget to initialize.
+ * @param name The name of the widget.
+ * @param class The class of the widget.
+ *
+ * Initializes the @widget structure.
+ *
+ */
 void widget_init ( widget *widget , const char *name, const char *class_name );
+
+/**
+ * @param widget The widget handle.
+ * @param state  The state of the widget.
+ *
+ * Set the state of the widget.
+ */
 void widget_set_state ( widget *widget, const char *state );
 
+/**
+ * @param wid The widget handle.
+ *
+ * Get the left padding of the widget.
+ *
+ * @returns the left padding in pixels.
+ */
 int widget_padding_get_left ( const widget *wid );
+
+/**
+ * @param wid The widget handle.
+ *
+ * Get the right padding of the widget.
+ *
+ * @returns the right padding in pixels.
+ */
 int widget_padding_get_right ( const widget *wid );
+
+/**
+ * @param wid The widget handle.
+ *
+ * Get the top padding of the widget.
+ *
+ * @returns the top padding in pixels.
+ */
 int widget_padding_get_top ( const widget *wid );
+
+/**
+ * @param wid The widget handle.
+ *
+ * Get the bottom padding of the widget.
+ *
+ * @returns the bottom padding in pixels.
+ */
 int widget_padding_get_bottom ( const widget *wid );
+
+/**
+ * @param wid The widget handle.
+ *
+ * Get width of the content of the widget 
+ *
+ * @returns the widget width, excluding padding. 
+ */
 int widget_padding_get_remaining_width ( const widget *wid );
+/**
+ * @param wid The widget handle.
+ *
+ * Get height of the content of the widget 
+ *
+ * @returns the widget height, excluding padding. 
+ */
 int widget_padding_get_remaining_height ( const widget *wid );
+/**
+ * @param wid The widget handle.
+ *
+ * Get the combined top and bottom padding.
+ *
+ * @returns the top and bottom padding of the widget in pixels.
+ */
 int widget_padding_get_padding_height ( const widget *wid );
+/**
+ * @param wid The widget handle.
+ *
+ * Get the combined left and right padding.
+ *
+ * @returns the left and right padding of the widget in pixels.
+ */
 int widget_padding_get_padding_width ( const widget *wid );
 #endif // WIDGET_INTERNAL_H
diff --git a/include/widgets/widget.h b/include/widgets/widget.h
index 03e85387..9dda0457 100644
--- a/include/widgets/widget.h
+++ b/include/widgets/widget.h
@@ -175,7 +175,22 @@ void widget_set_clicked_handler ( widget *wid, widget_clicked_cb cb, void *udata
 gboolean widget_motion_notify ( widget *wid, xcb_motion_notify_event_t *xme );
 
 
+/**
+ * @param wid The widget handle
+ * @param name The name of the widget.
+ *
+ * Set name on widget.
+ */
 void widget_set_name ( widget *wid, const char *name );
+
+/**
+ * @param wid The widget handle
+ *
+ * Get the desired height of this widget recursively.
+ *
+ * @returns the desired height of the widget in pixels.
+ */
 int widget_get_desired_height ( widget *wid );
+
 /*@}*/
 #endif // ROFI_WIDGET_H
diff --git a/include/widgets/window.h b/include/widgets/window.h
index 6d8a90a1..3c320d10 100644
--- a/include/widgets/window.h
+++ b/include/widgets/window.h
@@ -32,6 +32,13 @@ window * window_create ( const char *name );
  */
 void window_add ( window *window, widget *child );
 
+/**
+ * @param window Handle to the window widget.
+ * 
+ * Get the border width of the widget.
+ *
+ * @returns the border width (times 2) of the widget.
+ */
 int window_get_border_width ( const window *window );
 /*@}*/
 #endif // ROFI_WINDOW_H