[doc] Add a bunch of documentation

Signed-off-by: Julien Danjou <julien@danjou.info>

layout.c

@@ -122,7 +122,8 @@ layout_get_current(int screen)
     return l;
 }
 
-/** Set layout for tag
+/** Set layout for current tag.
+ * Argument must be a relative or absolute integer of available layouts.
  * \param screen Screen ID
  * \param arg Layout specifier
  * \ingroup ui_callback

mouse.c

@@ -125,7 +125,7 @@ mouse_resizebar_draw(DrawCtx *ctx, style_t style, SimpleWindow *sw, area_t geome
     simplewindow_refresh_drawable(sw, sw->phys_screen);
 }
 
-/** Move client with mouse
+/** Move client with the mouse.
  * \param screen Screen ID
  * \param arg Unused
  * \ingroup ui_callback
@@ -244,7 +244,7 @@ uicb_client_movemouse(int screen, char *arg __attribute__ ((unused)))
     }
 }
 
-/** Resize client with mouse
+/** Resize client with the mouse.
  * \param screen Screen ID
  * \param arg Unused
  * \ingroup ui_callback

screen.c

@@ -226,7 +226,8 @@ move_mouse_pointer_to_screen(int phys_screen)
 }
 
 
-/** Switch focus to a specified screen
+/** Switch focus to a specified screen.
+ * Argument must be an absolute or relative screen number.
  * \param screen Screen ID
  * \param arg screen number
  * \ingroup ui_callback
@@ -251,7 +252,8 @@ uicb_screen_focus(int screen, char *arg)
     move_mouse_pointer_to_screen(new_screen);
 }
 
-/** Move client to a virtual screen (if Xinerama is active)
+/** Move client to a screen.
+ * Argument must be an absolute or relative screen number.
  * \param screen Screen ID
  * \param arg screen number
  * \ingroup ui_callback

statusbar.c

@@ -300,7 +300,8 @@ statusbar_toggle(Statusbar *statusbar)
     globalconf.screens[statusbar->screen].need_arrange = True;
 }
 
-/** Toggle statusbar
+/** Toggle statusbar on or off.
+ * Argument must be a statusbar name, or no argument for all statusbars.
  * \param screen Screen ID
  * \param arg statusbar name
  * \ingroup ui_callback
@@ -320,5 +321,4 @@ uicb_statusbar_toggle(int screen, char *arg)
         statusbar_position_update(sb);
 }
 
-
 // vim: filetype=c:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=80

tag.c

@@ -61,6 +61,10 @@ tag_new(const char *name, Layout *layout, double mwfact, int nmaster, int ncol)
     return tag;
 }
 
+/** Append a tag to a screen.
+ * \param tag the tag to append
+ * \param screen the screen id
+ */
 void
 tag_append_to_screen(Tag *tag, int screen)
 {
@@ -73,6 +77,10 @@ tag_append_to_screen(Tag *tag, int screen)
     widget_invalidate_cache(screen, WIDGET_CACHE_TAGS);
 }
 
+/** Push a tag to a screen tag list.
+ * \param tag the tag to push
+ * \param screen the screen
+ */
 void
 tag_push_to_screen(Tag *tag, int screen)
 {
@@ -81,6 +89,10 @@ tag_push_to_screen(Tag *tag, int screen)
     widget_invalidate_cache(screen, WIDGET_CACHE_TAGS);
 }
 
+/** Tag a client with specified tag.
+ * \param c the client to tag
+ * \param t the tag to tag the client with
+ */
 void
 tag_client(Client *c, Tag *t)
 {
@@ -100,6 +112,10 @@ tag_client(Client *c, Tag *t)
     globalconf.screens[c->screen].need_arrange = True;
 }
 
+/** Untag a client with specified tag.
+ * \param c the client to tag
+ * \param t the tag to tag the client with
+ */
 void
 untag_client(Client *c, Tag *t)
 {
@@ -110,14 +126,18 @@ untag_client(Client *c, Tag *t)
         {
             tag_client_node_list_detach(&globalconf.tclink, tc);
             p_delete(&tc);
-            break;
-        }
-
             client_saveprops(c);
             widget_invalidate_cache(c->screen, WIDGET_CACHE_CLIENTS);
             globalconf.screens[c->screen].need_arrange = True;
+            break;
+        }
 }
 
+/** Check if a client is tagged with the specified tag.
+ * \param c the client
+ * \param t the tag
+ * \return true if the client is tagged with the tag, false otherwise.
+ */
 Bool
 is_client_tagged(Client *c, Tag *t)
 {
@@ -133,6 +153,9 @@ is_client_tagged(Client *c, Tag *t)
     return False;
 }
 
+/** Tag the client with the currently selected (visible) tags.
+ * \param c the client
+ */
 void
 tag_client_with_current_selected(Client *c)
 {
@@ -146,6 +169,10 @@ tag_client_with_current_selected(Client *c)
             untag_client(c, tag);
 }
 
+/** Tag the client according to a rule.
+ * \param c the client
+ * \param r the rule
+ */
 void
 tag_client_with_rule(Client *c, Rule *r)
 {
@@ -170,6 +197,11 @@ tag_client_with_rule(Client *c, Rule *r)
                 untag_client(c, tag);
 }
 
+/** Get the current tags for the specified screen.
+ * Returned pointer must be p_delete'd after.
+ * \param screen screen id
+ * \return a double pointer of tag list finished with a NULL element
+ */
 Tag **
 tags_get_current(int screen)
 {
@@ -190,7 +222,7 @@ tags_get_current(int screen)
     return tags;
 }
 
-/** Tag selected window with tag
+/** Tag focused client with tag.
  * \param screen Screen ID
  * \param arg Tag name
  * \ingroup ui_callback
@@ -225,7 +257,7 @@ uicb_client_tag(int screen, char *arg)
             tag_client(sel, tag);
 }
 
-/** Toggle a tag on client
+/** Toggle a tag on focused client.
  * \param screen virtual screen id
  * \param arg tag number
  * \ingroup ui_callback
@@ -274,7 +306,7 @@ uicb_client_toggletag(int screen, char *arg)
     }
 }
 
-/** Add a tag to viewed tags
+/** Add a tag to the list of viewed tags.
  * \param screen Screen ID
  * \param arg Tag name
  * \ingroup ui_callback
@@ -308,6 +340,9 @@ uicb_tag_toggleview(int screen, char *arg)
     p_delete(&curtags);
 }
 
+/** Set a tag to be the only one viewed.
+ * \param target the tag to see
+ */
 static void
 tag_view_only(Tag *target)
 {
@@ -319,6 +354,11 @@ tag_view_only(Tag *target)
         tag_view(tag, tag == target);
 }
 
+/** Use an index to set a tag viewable.
+ * \param screen the screen id
+ * \param dindex the index
+ * \param view the view value
+ */
 void
 tag_view_byindex(int screen, int dindex, Bool view)
 {
@@ -332,6 +372,10 @@ tag_view_byindex(int screen, int dindex, Bool view)
     tag_view(tag, view);
 }
 
+/** View only a tag, selected by its index.
+ * \param screen screen id
+ * \param dindex the index
+ */
 void
 tag_view_only_byindex(int screen, int dindex)
 {
@@ -345,6 +389,10 @@ tag_view_only_byindex(int screen, int dindex)
     tag_view_only(tag);
 }
 
+/** View or unview a tag.
+ * \param tag the tag
+ * \param view set visible or not
+ */
 void
 tag_view(Tag *tag, Bool view)
 {
@@ -355,7 +403,7 @@ tag_view(Tag *tag, Bool view)
     globalconf.screens[tag->screen].need_arrange = True;
 }
 
-/** View tag
+/** View tag.
  * \param screen Screen ID
  * \param arg tag to view
  * \ingroup ui_callback
@@ -386,7 +434,7 @@ uicb_tag_prev_selected(int screen, char *arg __attribute__ ((unused)))
         tag_view(tag, tag->was_selected);
 }
 
-/** View next tag
+/** View next tag.
  * \param screen Screen ID
  * \param arg unused
  * \ingroup ui_callback
@@ -404,7 +452,7 @@ uicb_tag_viewnext(int screen, char *arg __attribute__ ((unused)))
     p_delete(&curtags);
 }
 
-/** View previous tag
+/** View previous tag.
  * \param screen Screen ID
  * \param arg unused
  * \ingroup ui_callback
@@ -422,6 +470,10 @@ uicb_tag_viewprev(int screen, char *arg __attribute__ ((unused)))
     p_delete(&curtags);
 }
 
+/** Create a new tag. Argument must be the tag name.
+ * \param screen the screen id
+ * \param arg the tag name
+ */
 void
 uicb_tag_create(int screen, char *arg)
 {

titlebar.c

@@ -443,7 +443,7 @@ titlebar_update_geometry(Client *c, area_t geometry)
     titlebar_draw(c);
 }
 
-/** Toggle window titlebar visibility
+/** Toggle window titlebar visibility.
  * \param screen screen number (unused)
  * \param arg unused argument
  * \ingroup ui_callback

uicb.c

@@ -137,8 +137,12 @@ uicb_spawn(int screen, char *arg)
     wait(0);
 }
 
+/** Run the uicb
+ * \param cmd the uicb command to parse
+ * \return 0 on succes, -1 on failure
+ */
 static int
-run_uicb(char *cmd)
+uicb_run(char *cmd)
 {
     char *p, *argcpy;
     const char *arg;
@@ -190,6 +194,10 @@ run_uicb(char *cmd)
     return 0;
 }
 
+/** Parse the control buffer.
+ * \param cmd the control buffer
+ * \return 0 on succes, -1 on failure
+ */
 int
 parse_control(char *cmd)
 {
@@ -201,7 +209,7 @@ parse_control(char *cmd)
     while((p = strchr(curcmd, '\n')))
     {
         *p = '\0';
-        run_uicb(curcmd);
+        uicb_run(curcmd);
         curcmd = p + 1;
     }
 

widget.c

@@ -174,7 +174,7 @@ widget_invalidate_cache(int screen, int flags)
                 widget->cache.needs_update = True;
 }
 
-/** Send command to widget
+/** Send command to widgets.
  * \param screen Screen ID
  * \param arg Widget command. Syntax depends on specific widget.
  * \ingroup ui_callback