[doc] Autogenerate documentation for uicb from source code

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

.gitignore

@@ -27,3 +27,4 @@ layoutgen.h
 awesome-version-internal.h
 awesome-message
 awesome-menu
+uicbdocgen.txt

Makefile.am

@@ -219,6 +219,7 @@ clean-local:
 
 SUFFIXES += .1.xml .1
 SUFFIXES += .5.xml .5
+EXTRA_DIST += build-utils/extractdoc.py
 if HAVE_XMLTO
 .1.xml.1:
 	$(XMLTO) man $<
@@ -229,9 +230,11 @@ endif
 SUFFIXES += .1.txt .1.xml
 SUFFIXES += .5.txt .5.xml
 if HAVE_ASCIIDOC
+uicbdocgen.txt:
+	$(top_srcdir)/build-utils/extractdoc.py $(top_srcdir)/*.c > uicbdocgen.txt
 .1.txt.1.xml:
 	$(ASCIIDOC) -d manpage -b docbook -o $@ $<
-.5.txt.5.xml:
+.5.txt.5.xml: uicbdocgen.txt
 	$(ASCIIDOC) -d manpage -b docbook -o $@ $<
 endif
 

awesomerc.5.txt

@@ -246,101 +246,7 @@ In awesome, a lot of *functions* are available. These functions are called
 uicb (User Interface Call Backs). Each function can be bound to a key shortcut
 or a mouse button.
 
-General
+include::uicbdocgen.txt[]
-~~~~~~~
-*quit*::
-    This function quits awesome.
-*statusbar_toggle* statusbar-identifier::
-    Hide or show statusbar (with no argument, toggle all).
-*spawn* client::
-    Execute an external program.
-*exec* program::
-    Replace awesome with another window manager.
-*restart*::
-    Restart awesome.
-*widget_tell* widget-identifier data::
-    Feed information to your widgets.
-
-Client
-~~~~~~
-*client_kill*::
-    Closes the focused client.
-*client_moveresize* x y width height::
-    Dynamically move and resize floating windows.
-    Coordinates can be relative or absolute. Relative values must begin with + or -.
-    E.g: to move a window 10 pixels up: "+0 \+10 +0 +0" To move a window
-    in the upper left corner and increase its width by 10px: "0 0 \+0 +10"
-*client_settrans* float::
-    Set client transparency, number can be a relative or absolute floating number in percentage.
-*client_swapnext*::
-    Swap window placement with the next displayed window.
-*client_swapprev*::
-    Swap window placement with the previous displayed window.
-*client_focusnext*::
-    Focus next window.
-*client_focusprev*::
-    Focus previous window.
-*client_togglemax*::
-    Set window fullscreen. Calling this function another time will reset the window to its previous state.
-*client_togglehorizontalmax*::
-    Set window's horizontal size to display width. Calling another time will reset the window to its previous state.
-*client_toggleverticalmax*::
-    Set window's vertical size to display height. Calling another time will reset the window to its previous state.
-*client_togglefloating*::
-    Set window floating or tiled.
-*client_zoom*::
-    Set window as master window.
-*client_movetoscreen* relative or absolute integer::
-    Move focused window to the nth screen, or next (+1) or previous (-1). If no screen_number is set, move to the next screen.
-*client_tag* tag number::
-    Tag focused window with this tag.
-*client_toggletag*::
-    Add or remove tag to focused window.
-*client_movemouse*::
-    Move client window with mouse.
-*client_resizemouse*::
-    Resize client window with mouse.
-*client_setscratch*::
-    Set or unset client as being the scratch window.
-*client_togglescratch*::
-    Toggle scratch window.
-*client_toggletitlebar*::
-    Toggle window titlebar.
-
-Tag
-~~~
-*tag_setlayout* relative or absolute integer::
-    Set layout number; or just switch to the next layout for current tag.
-*tag_toggleview* tag::
-    Add windows tagged with tag number to current display.
-*tag_view* tag number::
-    View windows tagged with tag number.
-*tag_viewnext*::
-    Show windows tagged with next tag in list.
-*tag_viewprev*::
-    Show windows tagged with previous tag in list.
-*tag_prev_selected*::
-    Switch back to the previously displayed set of tags.
-*tag_setmwfact* relative or absolute float::
-    Set master width factor.
-*tag_setncol* relative or absolute integer::
-    Set number of columns for non-master windows.
-*tag_setnmaster* relative or absolute integer::
-    Set number of master windows.
-*tag_create* name::
-    Create a new tag with that name.
-
-Focus
-~~~~~
-*focus_client_byname* string::
-    Give client focus by its name.
-*focus_history* negative number::
-    Focus the client that had focused nth focus switch earlier.
-
-Screen
-~~~~~~
-*screen_focus* relative or absolute integer::
-    Select Screen and focus first window and move mouse.
 
 WIDGETS
 -------

build-utils/extractdoc.py

@@ -0,0 +1,70 @@
+#!/usr/bin/python
+#
+# extractdoc.py - extract uicb documentation from awesome sour code
+# Copyright ® 2008 Julien Danjou <julien@danjou.info>
+#
+# This indeed crappy. Any better version, even with awk, would be welcome.
+#
+
+import sys
+import os.path
+
+def extract_doc(file):
+    function_doc = {}
+    doc = []
+    doc_begin = False
+    catch_name = 0
+    
+    for line in file.readlines():
+        if catch_name == 1:
+            catch_name = 2
+            continue
+        if catch_name > 1:
+            # We only want functions with uicb
+            if line.startswith("uicb_"):
+                if line.endswith("arg __attribute__ ((unused)))\n"):
+                    doc.append("No argument needed.")
+                uicb_name = line.split('_', 1)[1]
+                uicb_name = uicb_name.split('(', 1)[0]
+                function_doc[uicb_name] = doc
+                catch_name = False
+            else:
+                catch_name = 0
+            doc = []
+        if line.startswith("/**"):
+            doc_begin = True
+            doc.append(line[4:].replace("\n", ""))
+        if doc_begin and line.startswith(" * ") and not line.startswith(" * \\"):
+            doc.append(line[3:].replace("\n", ""))
+        if line.startswith(" */"):
+            doc_begin = False
+            catch_name = 1
+
+    return function_doc
+
+def doc_print(function_doc, filename):
+    if not len(function_doc):
+        return
+    filename = os.path.basename(filename)
+    # Special case
+    if filename == "uicb.c":
+        filename = "general.c"
+    # Print header
+    tmptitle = filename.replace(".c", "")
+    title = tmptitle[0].upper() + tmptitle[1:]
+    print title
+    i = 0
+    underline = ""
+    while i < len(title):
+        underline += "~"
+        i += 1
+    print underline
+    # Print documentation
+    for uicb, doc in function_doc.items():
+        # Special case
+        print "*%s*::" % uicb
+        print "    %s" % " ".join(doc)
+    print
+
+for f in sys.argv[1:]:
+    doc_print(extract_doc(file(f)), f)

build-utils/uicbgen.sh

@@ -11,8 +11,6 @@ do
     do
         shortname=$(echo $uicb | cut -d _ -f2-)
         echo "    {\"$shortname\", $uicb},"
-        grep -q "\*$shortname\*" ${top_srcdir}/awesomerc.5.txt || \
-            echo "  WARNING: $uicb NOT documented" >&2
     done
 done
 

client.c

@@ -848,8 +848,7 @@ client_find_visible(Client *sel, Bool reverse)
  * \ingroup ui_callback
  */
 void
-uicb_client_swapprev(int screen __attribute__ ((unused)),
+uicb_client_swapprev(int screen __attribute__ ((unused)), char *arg __attribute__ ((unused)))
-                     char *arg __attribute__ ((unused)))
 {
     Client *prev;
 
@@ -866,8 +865,7 @@ uicb_client_swapprev(int screen __attribute__ ((unused)),
  * \ingroup ui_callback
  */
 void
-uicb_client_swapnext(int screen __attribute__ ((unused)),
+uicb_client_swapnext(int screen __attribute__ ((unused)), char *arg __attribute__ ((unused)))
-                     char *arg __attribute__ ((unused)))
 {
     Client *next;
 
@@ -1128,8 +1126,7 @@ uicb_client_focusprev(int screen, char *arg __attribute__ ((unused)))
  * \ingroup ui_callback
  */
 void
-uicb_client_togglefloating(int screen __attribute__ ((unused)),
+uicb_client_togglefloating(int screen __attribute__ ((unused)), char *arg __attribute__ ((unused)))
-                           char *arg __attribute__ ((unused)))
 {
     if(globalconf.focus->client)
         client_setfloating(globalconf.focus->client, !globalconf.focus->client->isfloating);
@@ -1141,8 +1138,7 @@ uicb_client_togglefloating(int screen __attribute__ ((unused)),
  * \ingroup ui_callback
  */
 void
-uicb_client_setscratch(int screen,
+uicb_client_setscratch(int screen, char *arg __attribute__ ((unused)))
-                       char *arg __attribute__ ((unused)))
 {
     if(!globalconf.focus->client)
         return;
@@ -1162,8 +1158,7 @@ uicb_client_setscratch(int screen,
  * \ingroup ui_callback
  */
 void
-uicb_client_togglescratch(int screen,
+uicb_client_togglescratch(int screen, char *arg __attribute__ ((unused)))
-                          char *arg __attribute__ ((unused)))
 {
     if(globalconf.scratch.client)
     {

titlebar.c

@@ -449,8 +449,7 @@ titlebar_update_geometry(Client *c, area_t geometry)
  * \ingroup ui_callback
  */
 void
-uicb_client_toggletitlebar(int screen __attribute__ ((unused)),
+uicb_client_toggletitlebar(int screen __attribute__ ((unused)), char *arg __attribute__ ((unused)))
-                            char *arg __attribute__ ((unused)))
 {
     Client *c = globalconf.focus->client;
 

uicb.c

@@ -47,15 +47,14 @@ extern AwesomeConf globalconf;
 #include "uicbgen.h"
 
 /** Restart awesome with the current command line
- * \param screen ID (unused)
+ * \param screen ID
  * \param arg arg (unused)
  * \ingroup ui_callback
  */
 void
-uicb_restart(int screen __attribute__ ((unused)),
+uicb_restart(int screen, char *arg __attribute__ ((unused)))
-             char *arg __attribute__ ((unused)))
 {
-    uicb_exec(0, globalconf.argv);
+    uicb_exec(screen, globalconf.argv);
 }
 
 /** Execute another process, replacing the current instance of Awesome