[doc] Add new Lua based documentation generator for API

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

.gitignore

@@ -22,3 +22,4 @@ awesomerc.lua
 widgetgen.h
 layoutgen.h
 awesome-version-internal.h
+apidocgen.txt

Makefile.am

@@ -43,6 +43,7 @@ EXTRA_DIST += LICENSE
 EXTRA_DIST += STYLE
 doc_DATA   += STYLE
 
+EXTRA_DIST += build-utils/gendoc.lua
 
 EXTRA_DIST    += awful.lua
 dist_awful_DATA += awful.lua
@@ -194,9 +195,14 @@ endif
 SUFFIXES += .1.txt .1.xml
 SUFFIXES += .5.txt .5.xml
 if HAVE_ASCIIDOC
+CLEANFILES    += apidocgen.txt
+BUILT_SOURCES += apidocgen.txt
+APIDOCSOURCES=$(shell grep -l 'const struct luaL_reg' $(awesome_SOURCES))
+apidocgen.txt: $(APIDOCSOURCES) build-utils/gendoc.lua
+	cat $(APIDOCSOURCES) | $(top_srcdir)/build-utils/gendoc.lua > apidocgen.txt
 .1.txt.1.xml:
 	$(ASCIIDOC) -d manpage -b docbook -o $@ $<
-awesomerc.5.xml:
+awesomerc.5.xml: apidocgen.txt
 .5.txt.5.xml:
 	$(ASCIIDOC) -d manpage -b docbook -o $@ $<
 endif

awesomerc.5.txt

@@ -4,7 +4,7 @@ awesomerc(5)
 NAME
 ----
 
-awesomerc - Configuration file for the 'awesome window manager'
+awesomerc - Configuration file for the awesome window manager
 
 SYNOPSIS
 --------
@@ -12,12 +12,15 @@ None.
 
 DESCRIPTION
 -----------
-
 The *awesomerc* file contains configuration informations for *awesome*. It can
 be used to configure the behaviour and look of awesome in a variety of ways.
+It can be assimilated as a Lua program/script run at startup by awesome.
+Therefore, it should use the awesome Lua API described in the API section.
+This file is read at startup.
 
-It is read at startup.
-
+AWESOME LUA API
+---------------
+include::apidocgen.txt[]
 
 SEE ALSO
 --------

build-utils/gendoc.lua

@@ -0,0 +1,63 @@
+#!/usr/bin/lua
+-- Generate documentation for awesome Lua functions
+-- Take a .c file in stdin
+
+function string.comment_clean(str)
+    local s = str:gsub("/%*%* ", "    ")
+    s = s:gsub(" %* ", " ")
+    s = s:gsub("\\param", "\n\n    Parameter:")
+    s = s:gsub("\\return", "\n\n    Return:")
+    return s
+end
+
+-- Read all the files in lines
+lines = io.read("*all")
+
+ilines = {}
+
+-- read the lines in table `ilines'
+for line in lines:gmatch("[^\r\n]+") do
+    table.insert(ilines, line)
+end
+
+-- Store function documentations in an array
+function_doc = {}
+for i, line in ipairs(ilines) do
+    if line:find("^/%*%*") then
+        comment_start = true
+        comment = line
+    elseif line:find("%*/") then
+        comment_start = false
+        local l = ilines[i + 2]
+        local fctname
+        _, _, fctname = l:find("^(.+)%(")
+        if fctname then
+            function_doc[fctname] = comment
+        end
+        comment = nil
+    elseif comment_start then
+        comment = comment .. line
+    end
+end
+
+-- Get function list and print their documentation
+capture = false
+for i, line in ipairs(ilines) do
+    if not libname then
+        _, _, libname, libtype = line:find("const struct luaL_reg awesome_(%a+)_(%a+)%[%] =")
+        -- Special case
+        if not libname then _, _, libname, libtype = line:find("const struct luaL_reg (awesome)_(lib)%[%] =") end
+    else
+        if line:find("};") then
+            libname = nil
+        else
+            local fctname, fctdef
+            _, _, fctname, fctdef = line:find("\"(.+)\", (.+) },")
+            if fctname and function_doc[fctdef] then
+                if libtype == "meta" then sep = ":" else sep = "." end
+                print("*" .. libname .. sep .. fctname ..  "*::")
+                print(function_doc[fctdef]:comment_clean())
+            end
+        end
+    end
+end

tag.c

@@ -289,8 +289,9 @@ luaA_tag_get(lua_State *L)
 }
 
 /** Create a new tag.
- * \param L Lua state.
- * \return One because there's one element, a user data.
+ * \param A table with at least a name attribute.
+ * Optionnal attributes are: mwfact, ncol, nmaster and layout.
+ * \return A new tag object.
  */
 static int
 luaA_tag_new(lua_State *L)