Merge pull request #266 from awesomeWM/juw-docs

docs: move documentation to C source

.travis.yml

@@ -85,6 +85,11 @@ install:
   # Install ldoc for building docs.
   - sudo luarocks install ldoc
 
+  # Install CMake 3+, via http://www.cmake.org/download/#latest.
+  - wget http://www.cmake.org/files/v3.2/cmake-3.2.3-Linux-x86_64.tar.Z
+  - tar xf cmake-3.2.3-Linux-x86_64.tar.Z
+  - PATH=$PWD/cmake-3.2.3-Linux-x86_64/bin:$PATH
+
 script:
   - export CMAKE_ARGS="-DLUA_LIBRARY=${LUALIB} -DLUA_INCLUDE_DIR=/usr/include/lua${LUAPKG}"
-  - make && sudo make install && awesome --version
+  - make && sudo env PATH=$PATH make install && awesome --version

CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 2.8.0)
+cmake_minimum_required(VERSION 3.0.0)
 set(CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS  TRUE)
 
 if(COMMAND cmake_policy)
@@ -15,7 +15,6 @@ endif()
 include(awesomeConfig.cmake)
 
 include_directories(
-    ${SOURCE_DIR}
     ${BUILD_DIR}
     ${AWESOME_COMMON_REQUIRED_INCLUDE_DIRS}
     ${AWESOME_REQUIRED_INCLUDE_DIRS}
@@ -36,45 +35,45 @@ set(AWE_DOC_FILES
     ${SOURCE_DIR}/LICENSE)
 
 set(AWE_SRCS
-    ${SOURCE_DIR}/awesome.c
-    ${SOURCE_DIR}/banning.c
-    ${SOURCE_DIR}/color.c
-    ${SOURCE_DIR}/dbus.c
-    ${SOURCE_DIR}/draw.c
-    ${SOURCE_DIR}/event.c
-    ${SOURCE_DIR}/ewmh.c
-    ${SOURCE_DIR}/keygrabber.c
-    ${SOURCE_DIR}/luaa.c
-    ${SOURCE_DIR}/mouse.c
-    ${SOURCE_DIR}/mousegrabber.c
-    ${SOURCE_DIR}/property.c
-    ${SOURCE_DIR}/root.c
-    ${SOURCE_DIR}/selection.c
-    ${SOURCE_DIR}/spawn.c
-    ${SOURCE_DIR}/stack.c
-    ${SOURCE_DIR}/strut.c
-    ${SOURCE_DIR}/systray.c
-    ${SOURCE_DIR}/xwindow.c
-    ${SOURCE_DIR}/xkb.c
-    ${SOURCE_DIR}/common/atoms.c
-    ${SOURCE_DIR}/common/backtrace.c
-    ${SOURCE_DIR}/common/buffer.c
-    ${SOURCE_DIR}/common/luaclass.c
-    ${SOURCE_DIR}/common/lualib.c
-    ${SOURCE_DIR}/common/luaobject.c
-    ${SOURCE_DIR}/common/util.c
-    ${SOURCE_DIR}/common/version.c
-    ${SOURCE_DIR}/common/xcursor.c
-    ${SOURCE_DIR}/common/xembed.c
-    ${SOURCE_DIR}/common/xutil.c
-    ${SOURCE_DIR}/objects/button.c
-    ${SOURCE_DIR}/objects/client.c
-    ${SOURCE_DIR}/objects/drawable.c
-    ${SOURCE_DIR}/objects/drawin.c
-    ${SOURCE_DIR}/objects/key.c
-    ${SOURCE_DIR}/objects/screen.c
-    ${SOURCE_DIR}/objects/tag.c
-    ${SOURCE_DIR}/objects/window.c)
+    ${BUILD_DIR}/awesome.c
+    ${BUILD_DIR}/banning.c
+    ${BUILD_DIR}/color.c
+    ${BUILD_DIR}/dbus.c
+    ${BUILD_DIR}/draw.c
+    ${BUILD_DIR}/event.c
+    ${BUILD_DIR}/ewmh.c
+    ${BUILD_DIR}/keygrabber.c
+    ${BUILD_DIR}/luaa.c
+    ${BUILD_DIR}/mouse.c
+    ${BUILD_DIR}/mousegrabber.c
+    ${BUILD_DIR}/property.c
+    ${BUILD_DIR}/root.c
+    ${BUILD_DIR}/selection.c
+    ${BUILD_DIR}/spawn.c
+    ${BUILD_DIR}/stack.c
+    ${BUILD_DIR}/strut.c
+    ${BUILD_DIR}/systray.c
+    ${BUILD_DIR}/xwindow.c
+    ${BUILD_DIR}/xkb.c
+    ${BUILD_DIR}/common/atoms.c
+    ${BUILD_DIR}/common/backtrace.c
+    ${BUILD_DIR}/common/buffer.c
+    ${BUILD_DIR}/common/luaclass.c
+    ${BUILD_DIR}/common/lualib.c
+    ${BUILD_DIR}/common/luaobject.c
+    ${BUILD_DIR}/common/util.c
+    ${BUILD_DIR}/common/version.c
+    ${BUILD_DIR}/common/xcursor.c
+    ${BUILD_DIR}/common/xembed.c
+    ${BUILD_DIR}/common/xutil.c
+    ${BUILD_DIR}/objects/button.c
+    ${BUILD_DIR}/objects/client.c
+    ${BUILD_DIR}/objects/drawable.c
+    ${BUILD_DIR}/objects/drawin.c
+    ${BUILD_DIR}/objects/key.c
+    ${BUILD_DIR}/objects/screen.c
+    ${BUILD_DIR}/objects/tag.c
+    ${BUILD_DIR}/objects/window.c)
 
 set(AWE_MAN_SRCS
     ${SOURCE_DIR}/manpages/awesome.1.txt
@@ -225,21 +224,13 @@ if(GENERATE_MANPAGES)
 endif()
 # }}}
 
-# {{{ Doxygen
-if(DOXYGEN_EXECUTABLE)
-    add_custom_target(doc
-        COMMAND ${DOXYGEN_EXECUTABLE} awesome.doxygen
-        WORKING_DIRECTORY ${BUILD_DIR})
-endif()
-# }}}
-
 # {{{ Lua API Documentation
 if(GENERATE_DOC)
     if(NOT BUILD_DIR STREQUAL SOURCE_DIR)
         file(MAKE_DIRECTORY ${BUILD_DIR}/lib)
     endif()
 
-    file(GLOB_RECURSE AWE_LUA_FILES ${BUILD_DIR}/lib/*.lua ${AWE_DOC_DIR}/capi/*.lua)
+    file(GLOB_RECURSE AWE_LUA_FILES ${BUILD_DIR}/lib/*.lua)
     file(GLOB_RECURSE AWE_MD_FILES ${AWE_DOC_DIR}/*.md)
 
     add_custom_target(ldoc ALL

awesome.doxygen.in

@@ -1,246 +0,0 @@
-DOXYFILE_ENCODING      = UTF-8
-PROJECT_NAME           = awesome
-PROJECT_NUMBER         = devel
-OUTPUT_DIRECTORY       = doc
-CREATE_SUBDIRS         = NO
-OUTPUT_LANGUAGE        = English
-BRIEF_MEMBER_DESC      = YES
-REPEAT_BRIEF           = YES
-ABBREVIATE_BRIEF       = "The $name class" \
-                         "The $name widget" \
-                         "The $name file" \
-                         is \
-                         provides \
-                         specifies \
-                         contains \
-                         represents \
-                         a \
-                         an \
-                         the
-ALWAYS_DETAILED_SEC    = NO
-INLINE_INHERITED_MEMB  = NO
-FULL_PATH_NAMES        = YES
-STRIP_FROM_PATH        = 
-STRIP_FROM_INC_PATH    = 
-SHORT_NAMES            = NO
-JAVADOC_AUTOBRIEF      = NO
-QT_AUTOBRIEF           = NO
-MULTILINE_CPP_IS_BRIEF = NO
-INHERIT_DOCS           = YES
-SEPARATE_MEMBER_PAGES  = NO
-TAB_SIZE               = 4
-ALIASES                = 
-OPTIMIZE_OUTPUT_FOR_C  = YES
-OPTIMIZE_OUTPUT_JAVA   = NO
-BUILTIN_STL_SUPPORT    = NO
-CPP_CLI_SUPPORT        = NO
-DISTRIBUTE_GROUP_DOC   = NO
-SUBGROUPING            = YES
-
-ALIASES += luastack="\par Lua Stack:"
-ALIASES += lvalue="- \em value "
-ALIASES += lparam="- \em param "
-ALIASES += lreturn="- \em returns "
-ALIASES += lfield="- \em fields "
-
-#---------------------------------------------------------------------------
-# Build related configuration options
-#---------------------------------------------------------------------------
-EXTRACT_ALL            = YES
-EXTRACT_PRIVATE        = YES
-EXTRACT_STATIC         = YES
-EXTRACT_LOCAL_CLASSES  = YES
-EXTRACT_LOCAL_METHODS  = YES
-EXTRACT_ANON_NSPACES   = YES
-HIDE_UNDOC_MEMBERS     = NO
-HIDE_UNDOC_CLASSES     = NO
-HIDE_FRIEND_COMPOUNDS  = NO
-HIDE_IN_BODY_DOCS      = NO
-INTERNAL_DOCS          = NO
-CASE_SENSE_NAMES       = YES
-HIDE_SCOPE_NAMES       = NO
-SHOW_INCLUDE_FILES     = YES
-INLINE_INFO            = YES
-SORT_MEMBER_DOCS       = YES
-SORT_BRIEF_DOCS        = NO
-SORT_BY_SCOPE_NAME     = NO
-GENERATE_TODOLIST      = YES
-GENERATE_TESTLIST      = YES
-GENERATE_BUGLIST       = YES
-GENERATE_DEPRECATEDLIST= YES
-ENABLED_SECTIONS       = 
-MAX_INITIALIZER_LINES  = 30
-SHOW_USED_FILES        = YES
-FILE_VERSION_FILTER    = 
-#---------------------------------------------------------------------------
-# configuration options related to warning and progress messages
-#---------------------------------------------------------------------------
-QUIET                  = YES
-WARNINGS               = YES
-WARN_IF_UNDOCUMENTED   = YES
-WARN_IF_DOC_ERROR      = YES
-WARN_NO_PARAMDOC       = NO
-WARN_FORMAT            = "$file:$line: $text"
-WARN_LOGFILE           = 
-#---------------------------------------------------------------------------
-# configuration options related to the input files
-#---------------------------------------------------------------------------
-INPUT                  = @awesome_SOURCE_DIR@
-INPUT_ENCODING         = UTF-8
-FILE_PATTERNS          = *.c \
-                         *.h \
-                         common/*.c \
-                         common/*.h \
-                         widgets/*.c \
-                         widgets/*.h \
-RECURSIVE              = YES
-EXCLUDE                = 
-EXCLUDE_SYMLINKS       = NO
-EXCLUDE_PATTERNS       =
-EXCLUDE_SYMBOLS        = 
-EXAMPLE_PATH           = 
-EXAMPLE_PATTERNS       = *
-EXAMPLE_RECURSIVE      = NO
-IMAGE_PATH             = 
-INPUT_FILTER           = 
-FILTER_PATTERNS        = 
-FILTER_SOURCE_FILES    = NO
-#---------------------------------------------------------------------------
-# configuration options related to source browsing
-#---------------------------------------------------------------------------
-SOURCE_BROWSER         = YES
-INLINE_SOURCES         = NO
-STRIP_CODE_COMMENTS    = NO
-REFERENCED_BY_RELATION = YES
-REFERENCES_RELATION    = YES
-REFERENCES_LINK_SOURCE = YES
-USE_HTAGS              = NO
-VERBATIM_HEADERS       = YES
-#---------------------------------------------------------------------------
-# configuration options related to the alphabetical class index
-#---------------------------------------------------------------------------
-ALPHABETICAL_INDEX     = NO
-COLS_IN_ALPHA_INDEX    = 5
-IGNORE_PREFIX          = 
-#---------------------------------------------------------------------------
-# configuration options related to the HTML output
-#---------------------------------------------------------------------------
-GENERATE_HTML          = YES
-HTML_OUTPUT            = html
-HTML_FILE_EXTENSION    = .html
-HTML_HEADER            = 
-HTML_FOOTER            = 
-HTML_STYLESHEET        = 
-GENERATE_HTMLHELP      = NO
-HTML_DYNAMIC_SECTIONS  = NO
-CHM_FILE               = 
-HHC_LOCATION           = 
-GENERATE_CHI           = NO
-BINARY_TOC             = NO
-TOC_EXPAND             = NO
-DISABLE_INDEX          = NO
-ENUM_VALUES_PER_LINE   = 4
-GENERATE_TREEVIEW      = YES
-TREEVIEW_WIDTH         = 250
-#---------------------------------------------------------------------------
-# configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
-GENERATE_LATEX         = NO
-LATEX_OUTPUT           = latex
-LATEX_CMD_NAME         = latex
-MAKEINDEX_CMD_NAME     = makeindex
-COMPACT_LATEX          = NO
-PAPER_TYPE             = a4wide
-EXTRA_PACKAGES         = 
-LATEX_HEADER           = 
-PDF_HYPERLINKS         = NO
-USE_PDFLATEX           = NO
-LATEX_BATCHMODE        = NO
-LATEX_HIDE_INDICES     = NO
-#---------------------------------------------------------------------------
-# configuration options related to the RTF output
-#---------------------------------------------------------------------------
-GENERATE_RTF           = NO
-RTF_OUTPUT             = rtf
-COMPACT_RTF            = NO
-RTF_HYPERLINKS         = NO
-RTF_STYLESHEET_FILE    = 
-RTF_EXTENSIONS_FILE    = 
-#---------------------------------------------------------------------------
-# configuration options related to the man page output
-#---------------------------------------------------------------------------
-GENERATE_MAN           = NO
-MAN_OUTPUT             = man
-MAN_EXTENSION          = .3
-MAN_LINKS              = NO
-#---------------------------------------------------------------------------
-# configuration options related to the XML output
-#---------------------------------------------------------------------------
-GENERATE_XML           = NO
-XML_OUTPUT             = xml
-XML_SCHEMA             = 
-XML_DTD                = 
-XML_PROGRAMLISTING     = YES
-#---------------------------------------------------------------------------
-# configuration options for the AutoGen Definitions output
-#---------------------------------------------------------------------------
-GENERATE_AUTOGEN_DEF   = NO
-#---------------------------------------------------------------------------
-# configuration options related to the Perl module output
-#---------------------------------------------------------------------------
-GENERATE_PERLMOD       = NO
-PERLMOD_LATEX          = NO
-PERLMOD_PRETTY         = YES
-PERLMOD_MAKEVAR_PREFIX = 
-#---------------------------------------------------------------------------
-# Configuration options related to the preprocessor   
-#---------------------------------------------------------------------------
-ENABLE_PREPROCESSING   = YES
-MACRO_EXPANSION        = YES
-EXPAND_ONLY_PREDEF     = YES
-SEARCH_INCLUDES        = YES
-INCLUDE_PATH           = 
-INCLUDE_FILE_PATTERNS  = 
-PREDEFINED             = WITH_DBUS = \
-			 "__attribute__(x)="
-EXPAND_AS_DEFINED      = 
-SKIP_FUNCTION_MACROS   = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to external references   
-#---------------------------------------------------------------------------
-TAGFILES               = 
-GENERATE_TAGFILE       = 
-ALLEXTERNALS           = NO
-EXTERNAL_GROUPS        = YES
-PERL_PATH              = /usr/bin/perl
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool   
-#---------------------------------------------------------------------------
-CLASS_DIAGRAMS         = NO
-MSCGEN_PATH            = 
-HIDE_UNDOC_RELATIONS   = YES
-HAVE_DOT               = YES
-CLASS_GRAPH            = YES
-COLLABORATION_GRAPH    = YES
-GROUP_GRAPHS           = YES
-UML_LOOK               = YES
-TEMPLATE_RELATIONS     = YES
-INCLUDE_GRAPH          = YES
-INCLUDED_BY_GRAPH      = YES
-CALL_GRAPH             = YES
-CALLER_GRAPH           = YES
-GRAPHICAL_HIERARCHY    = YES
-DIRECTORY_GRAPH        = YES
-DOT_IMAGE_FORMAT       = png
-DOT_PATH               = 
-DOTFILE_DIRS           = 
-DOT_GRAPH_MAX_NODES    = 50
-MAX_DOT_GRAPH_DEPTH    = 1000
-DOT_TRANSPARENT        = YES
-DOT_MULTI_TARGETS      = NO
-GENERATE_LEGEND        = YES
-DOT_CLEANUP            = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to the search engine   
-#---------------------------------------------------------------------------
-SEARCHENGINE           = NO

awesomeConfig.cmake

@@ -56,12 +56,10 @@ if(NOT LDOC_EXECUTABLE)
 endif()
 # theme graphics
 a_find_program(CONVERT_EXECUTABLE convert TRUE)
-# doxygen
-include(FindDoxygen)
 # pkg-config
 include(FindPkgConfig)
-# lua 5.1
-include(FindLua51)
+# lua
+include(FindLua)
 # }}}
 
 # {{{ Check if documentation can be build
@@ -189,11 +187,6 @@ else()
     message(STATUS "checking for __builtin_clz -- no")
 endif()
 
-# Error check
-if(NOT LUA51_FOUND AND NOT LUA50_FOUND) # This is a workaround to a cmake bug
-    message(FATAL_ERROR "lua library not found")
-endif()
-
 set(AWESOME_REQUIRED_LDFLAGS
     ${AWESOME_COMMON_REQUIRED_LDFLAGS}
     ${AWESOME_REQUIRED_LDFLAGS}
@@ -284,31 +277,43 @@ set(AWESOME_THEMES_PATH      ${AWESOME_DATA_PATH}/themes)
 # }}}
 
 # {{{ Configure files
+file(GLOB_RECURSE awesome_c_configure_files RELATIVE
+    ${SOURCE_DIR}
+    ${SOURCE_DIR}/*.c
+    ${SOURCE_DIR}/*.h
+    ${SOURCE_DIR}/*/*.c
+    ${SOURCE_DIR}/*/*.h)
 file(GLOB_RECURSE awesome_lua_configure_files RELATIVE
     ${SOURCE_DIR}
-    ${SOURCE_DIR}/lib/*.lua.in
-    ${SOURCE_DIR}/docs/capi/*.lua.in
-    ${SOURCE_DIR}/docs/*.md
-    ${SOURCE_DIR}/themes/*/*.lua.in)
+    ${SOURCE_DIR}/lib/*.lua
+    ${SOURCE_DIR}/themes/*/*.lua)
 set(AWESOME_CONFIGURE_FILES
+    ${awesome_c_configure_files}
     ${awesome_lua_configure_files}
-    config.h.in
-    docs/config.ld.in
-    awesomerc.lua.in
-    awesome-version-internal.h.in
-    awesome.doxygen.in)
-
-macro(a_configure_file file)
-    string(REGEX REPLACE ".in\$" "" outfile ${file})
-    message(STATUS "Configuring ${outfile}")
-    configure_file(${SOURCE_DIR}/${file}
-                   ${BUILD_DIR}/${outfile}
-                   ESCAPE_QUOTE
-                   @ONLY)
-endmacro()
+    config.h
+    docs/config.ld
+    awesomerc.lua
+    awesome-version-internal.h)
 
 foreach(file ${AWESOME_CONFIGURE_FILES})
-    a_configure_file(${file})
+    configure_file(${SOURCE_DIR}/${file}
+                   ${BUILD_DIR}/${file}
+                   ESCAPE_QUOTES
+                   @ONLY)
+endforeach()
+#}}}
+
+# {{{ Copy additional files
+file(GLOB_RECURSE awesome_md_docs RELATIVE
+    ${SOURCE_DIR}
+    ${SOURCE_DIR}/docs/*.md)
+set(AWESOME_ADDITIONAL_FILES
+    ${awesome_md_docs})
+
+foreach(file ${AWESOME_ADDITIONAL_FILES})
+    configure_file(${SOURCE_DIR}/${file}
+                   ${BUILD_DIR}/${file}
+                   COPYONLY)
 endforeach()
 #}}}
 

common/luaobject.c

@@ -19,6 +19,14 @@
  *
  */
 
+/** Handling of signals.
+ *
+ * This can not be used as a standalone class, but is instead referenced
+ * explicitely in the classes, where it can be used. In the respective classes,
+ * it then can be used via `classname:connect_signal(...)` etc.
+ * @classmod signals
+ */
+
 #include "common/luaobject.h"
 #include "common/backtrace.h"
 
@@ -160,6 +168,11 @@ luaA_settype(lua_State *L, lua_class_t *lua_class)
     return 1;
 }
 
+/** Add a signal.
+ * @tparam string name A signal name.
+ * @tparam func func A function to call when the signal is emitted.
+ * @function connect_signal
+ */
 void
 luaA_object_connect_signal(lua_State *L, int oud,
                            const char *name, lua_CFunction fn)
@@ -168,6 +181,11 @@ luaA_object_connect_signal(lua_State *L, int oud,
     luaA_object_connect_signal_from_stack(L, oud, name, -1);
 }
 
+/** Remove a signal.
+ * @tparam string name A signal name.
+ * @tparam func func A function to remove.
+ * @function disconnect_signal
+ */
 void
 luaA_object_disconnect_signal(lua_State *L, int oud,
                               const char *name, lua_CFunction fn)
@@ -242,11 +260,10 @@ signal_object_emit(lua_State *L, signal_array_t *arr, const char *name, int narg
     lua_pop(L, nargs);
 }
 
-/** Emit a signal to an object.
- * \param L The Lua VM state.
- * \param oud The object index on the stack.
- * \param name The name of the signal.
- * \param nargs The number of arguments to pass to the called functions.
+/** Emit a signal.
+ * @tparam string name A signal name.
+ * @param[opt] ... Various arguments.
+ * @function emit_signal
  */
 void
 luaA_object_emit_signal(lua_State *L, int oud,

dbus.c

@@ -19,6 +19,13 @@
  *
  */
 
+/** awesome D-Bus API
+ * @author Julien Danjou <julien@danjou.info>
+ * @copyright 2008-2009 Julien Danjou
+ * @release @AWESOME_VERSION@
+ * @module dbus
+ */
+
 #include "config.h"
 #include "dbus.h"
 
@@ -666,12 +673,11 @@ a_dbus_bus_getbyname(const char *name)
 }
 
 /** Register a D-Bus name to receive message from.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam A string indicating if we are using system or session bus.
- * \lparam A string with the name of the D-Bus name to register.
- * \lreturn True if everything worked fine, false otherwise.
+ *
+ * @param bus A string indicating if we are using system or session bus.
+ * @param name A string with the name of the D-Bus name to register.
+ * @return True if everything worked fine, false otherwise.
+ * @function request_name
  */
 static int
 luaA_dbus_request_name(lua_State *L)
@@ -684,12 +690,11 @@ luaA_dbus_request_name(lua_State *L)
 }
 
 /** Release a D-Bus name.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam A string indicating if we are using system or session bus.
- * \lparam A string with the name of the D-Bus name to unregister.
- * \lreturn True if everything worked fine, false otherwise.
+ *
+ * @param bus A string indicating if we are using system or session bus.
+ * @param name A string with the name of the D-Bus name to unregister.
+ * @return True if everything worked fine, false otherwise.
+ * @function release_name
  */
 static int
 luaA_dbus_release_name(lua_State *L)
@@ -702,11 +707,10 @@ luaA_dbus_release_name(lua_State *L)
 }
 
 /** Add a match rule to match messages going through the message bus.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam A string indicating if we are using system or session bus.
- * \lparam A string with the name of the match rule.
+ *
+ * @param bus A string indicating if we are using system or session bus.
+ * @param name A string with the name of the match rule.
+ * @function add_match
  */
 static int
 luaA_dbus_add_match(lua_State *L)
@@ -726,11 +730,10 @@ luaA_dbus_add_match(lua_State *L)
 
 /** Remove a previously added match rule "by value"
  * (the most recently-added identical rule gets removed).
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam A string indicating if we are using system or session bus.
- * \lparam A string with the name of the match rule.
+ *
+ * @param bus A string indicating if we are using system or session bus.
+ * @param name A string with the name of the match rule.
+ * @function remove_match
  */
 static int
 luaA_dbus_remove_match(lua_State *L)
@@ -749,11 +752,10 @@ luaA_dbus_remove_match(lua_State *L)
 }
 
 /** Add a signal receiver on the D-Bus.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam A string with the interface name.
- * \lparam The function to call.
+ *
+ * @param interface A string with the interface name.
+ * @param func The function to call.
+ * @function connect_signal
  */
 static int
 luaA_dbus_connect_signal(lua_State *L)
@@ -772,12 +774,11 @@ luaA_dbus_connect_signal(lua_State *L)
     return 0;
 }
 
-/** Add a signal receiver on the D-Bus.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam A string with the interface name.
- * \lparam The function to call.
+/** Remove a signal receiver on the D-Bus.
+ *
+ * @param interface A string with the interface name.
+ * @param func The function to call.
+ * @function disconnect_signal
  */
 static int
 luaA_dbus_disconnect_signal(lua_State *L)
@@ -791,18 +792,17 @@ luaA_dbus_disconnect_signal(lua_State *L)
 }
 
 /** Emit a signal on the D-Bus.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam A string indicating if we are using system or session bus.
- * \lparam A string with the dbus path.
- * \lparam A string with the dbus interface.
- * \lparam A string with the dbus method name.
- * \lparam type of 1st arg
- * \lparam 1st arg value
- * \lparam type of 2nd arg
- * \lparam 2nd arg value
+ *
+ * @param bus A string indicating if we are using system or session bus.
+ * @param path A string with the dbus path.
+ * @param interface A string with the dbus interface.
+ * @param method A string with the dbus method name.
+ * @param type_1st_arg type of 1st argument
+ * @param value_1st_arg value of 1st argument
+ * @param type_2nd_arg type of 2nd argument
+ * @param value_2nd_arg value of 2nd argument
  * ... etc
+ * @function emit_signal
  */
 static int
 luaA_dbus_emit_signal(lua_State *L)

docs/capi/awesome.lua.in

@@ -1,90 +0,0 @@
---- awesome core API
--- @author Julien Danjou <julien@danjou.info>
--- @copyright 2008-2009 Julien Danjou
--- @release @AWESOME_VERSION@
--- @module awesome
-
---- awesome global table.
---
--- @field version The version of awesome.
--- @field release The release name of awesome.
--- @field conffile The configuration file which has been loaded.
--- @field startup True if we are still in startup, false otherwise.
--- @field startup_errors Error message for errors that occured during startup.
--- @field composite_manager_running True if a composite manager is running.
--- @table awesome
-
---- Quit awesome.
---
--- @function quit
-
---- Execute another application, probably a window manager, to replace
--- awesome.
---
--- @param cmd The command line to execute.
--- @function exec
-
---- Restart awesome.
---
--- @name restart
--- @class function
-
---- Spawn a program.
---
--- @param cmd The command to launch. Either a string or a table of strings.
--- @param use_sn Use startup-notification, true or false, default to true.
--- @return Process ID if everything is OK, or an error string if an error occured.
-
---- Load an image
---
--- @param name The file name
--- @return A cairo image surface as light user datum
--- @function load_image
-
---- Register a new xproperty.
---
--- @param name The name of the X11 property
--- @param type One of "string", "number" or "boolean"
--- @function register_xproperty
-
---- Change a xproperty.
---
--- @param name The name of the X11 property
--- @param value The new value for the property
--- @function set_xproperty
-
---- Get the value of a xproperty.
---
--- @param name The name of the X11 property
--- @function get_xproperty
-
---- Add a global signal.
---
--- @param name A string with the event name.
--- @param func The function to call.
--- @function connect_signal
-
---- Remove a global signal.
---
--- @param name A string with the event name.
--- @param func The function to call.
--- @function disconnect_signal
-
---- Emit a global signal.
---
--- @param name A string with the event name.
--- @param ... Signal arguments.
--- @function emit_signal
-
---- Switch keyboard layout group.
--- @param num keyboard layout number, integer from 0 to 3
--- @function xkb_set_layout_group
-
---- Get current keyboard layout group.
--- @return current keyboard layout number
--- @function xkb_get_layout_group
-
-
---- Get description of configured layouts
--- @return String with description of configured layouts
--- @function xkb_get_group_names

docs/capi/button.lua.in

@@ -1,31 +0,0 @@
---- awesome button API
--- @author Julien Danjou <julien@danjou.info>
--- @copyright 2008-2009 Julien Danjou
--- @release @AWESOME_VERSION@
--- @classmod button
-
---- Button object.
---
--- @tfield int button The mouse button number, or 0 for any button.
--- @tfield table modifiers The modifier key table that should be pressed while the
---   button is pressed.
--- @table button
-
---- Add a signal.
--- @tparam string name A signal name.
--- @tparam func func A function to call when the signal is emitted.
--- @function connect_signal
-
---- Remove a signal.
--- @tparam string name A signal name.
--- @tparam func func A function to remove.
--- @function disconnect_signal
-
---- Emit a signal.
--- @tparam string name A signal name.
--- @param[opt] ... Various arguments.
--- @function emit_signal
-
---- Get the number of instances.
--- @treturn int The number of button objects alive.
--- @function instances

docs/capi/client.lua.in

@@ -1,156 +0,0 @@
---- awesome client API
--- @author Julien Danjou <julien@danjou.info>
--- @copyright 2008-2009 Julien Danjou
--- @release @AWESOME_VERSION@
--- @classmod client
-
---- Client object.
---
--- @field window The X window id.
--- @field name The client title.
--- @field skip_taskbar True if the client does not want to be in taskbar.
--- @field type The window type (desktop, normal, dock, …).
--- @field class The client class.
--- @field instance The client instance.
--- @field pid The client PID, if available.
--- @field role The window role, if available.
--- @field machine The machine client is running on.
--- @field icon_name The client name when iconified.
--- @field icon The client icon.
--- @field screen Client screen.
--- @field hidden Define if the client must be hidden, i.e. never mapped,
---   invisible in taskbar.
--- @field minimized Define it the client must be iconify, i.e. only visible in
---   taskbar.
--- @field size_hints_honor Honor size hints, i.e. respect size ratio.
--- @field border_width The client border width.
--- @field border_color The client border color.
--- @field urgent The client urgent state.
--- @field content An image representing the client window content (screenshot).
--- @field focus The focused client.
--- @field opacity The client opacity between 0 and 1.
--- @field ontop The client is on top of every other windows.
--- @field above The client is above normal windows.
--- @field below The client is below normal windows.
--- @field fullscreen The client is fullscreen or not.
--- @field maximized The client is maximized (horizontally and vertically) or not.
--- @field maximized_horizontal The client is maximized horizontally or not.
--- @field maximized_vertical The client is maximized vertically or not.
--- @field transient_for The client the window is transient for.
--- @field group_window Window identification unique to a group of windows.
--- @field leader_window Identification unique to windows spawned by the same command.
--- @field size_hints A table with size hints of the client: user_position,
---   user_size, program_position, program_size, etc.
--- @field sticky Set the client sticky, i.e. available on all tags.
--- @field modal Indicate if the client is modal.
--- @field focusable True if the client can receive the input focus.
--- @field shape_bounding The client's bounding shape as set by awesome as a (native) cairo surface.
--- @field shape_clip The client's clip shape as set by awesome as a (native) cairo surface.
--- @field shape_client_bounding The client's bounding shape as set by the program as a (native) cairo surface.
--- @field shape_client_clip The client's clip shape as set by the program as a (native) cairo surface.
--- @field startup_id The FreeDesktop StartId.
--- @field valid If the client that this object refers to is still managed by awesome.
--- @table client
-
---- Get all clients into a table.
---
--- @param[opt] screen A screen number.
--- @return A table with all clients.
--- @function get
-
---- Check if a client is visible on its screen.
---
--- @return A boolean value, true if the client is visible, false otherwise.
--- @function isvisible
-
---- Return client geometry.
---
--- @param arg1 A table with new coordinates, or none.
--- @return A table with client coordinates.
--- @function geometry
-
---- Apply size hints to a size.
--- @param width Desired width of client
--- @param height Desired height of client
--- @return Actual width of client
--- @return Actual height of client
--- @name apply_size_hints
--- @class function
-
---- Return client struts (reserved space at the edge of the screen).
---
--- @param struts A table with new strut values, or none.
--- @return A table with strut values.
--- @function struts
-
---- Get or set mouse buttons bindings for a client.
---
--- @param buttons_table An array of mouse button bindings objects, or nothing.
--- @return A table with all buttons.
--- @function buttons
-
---- Get or set keys bindings for a client.
---
--- @param keys_table An array of key bindings objects, or nothing.
--- @return A table with all keys.
--- @function keys
-
---- Access or set the client tags.
---
--- @param tags_table A table with tags to set, or none to get the current tags table.
--- @return A table with all tags.
--- @function tags
-
---- Kill a client.
---
--- @function kill
-
---- Swap a client with another one in global client list.
--- @client A client to swap with.
--- @function swap
-
---- Raise a client on top of others which are on the same layer.
---
--- @function raise
-
---- Lower a client on bottom of others which are on the same layer.
---
--- @function lower
-
---- Stop managing a client.
---
--- @function unmanage
-
---- Change a xproperty.
---
--- @param name The name of the X11 property
--- @param value The new value for the property
--- @function set_xproperty
-
---- Get the value of a xproperty.
---
--- @param name The name of the X11 property
--- @function get_xproperty
-
---- Add a signal.
---
--- @param name A signal name.
--- @param func A function to call when the signal is emitted.
--- @function connect_signal
-
---- Remove a signal.
---
--- @param name A signal name.
--- @param func A function to remove.
--- @function disconnect_signal
-
---- Emit a signal.
---
--- @param name A signal name.
--- @param[opt] ... Various arguments.
--- @function emit_signal
-
---- Get the number of instances.
---
--- @return The number of client objects alive.
--- @function instances

docs/capi/dbus.lua.in

@@ -1,56 +0,0 @@
---- awesome D-Bus API
--- @author Julien Danjou <julien@danjou.info>
--- @copyright 2008-2009 Julien Danjou
--- @release @AWESOME_VERSION@
--- @module dbus
-
---- Register a D-Bus name to receive message from.
---
--- @param bus A string indicating if we are using system or session bus.
--- @param name A string with the name of the D-Bus name to register.
--- @return True if everything worked fine, false otherwise.
--- @function request_name
-
---- Release a D-Bus name.
---
--- @param bus A string indicating if we are using system or session bus.
--- @param name A string with the name of the D-Bus name to unregister.
--- @return True if everything worked fine, false otherwise.
--- @function release_name
-
---- Add a match rule to match messages going through the message bus.
---
--- @param bus A string indicating if we are using system or session bus.
--- @param name A string with the name of the match rule.
--- @function add_match
-
---- Remove a previously added match rule "by value"
--- (the most recently-added identical rule gets removed).
---
--- @param bus A string indicating if we are using system or session bus.
--- @param name A string with the name of the match rule.
--- @function remove_match
-
---- Add a signal receiver on the D-Bus.
---
--- @param interface A string with the interface name.
--- @param func The function to call.
--- @function connect_signal
-
---- Remove a signal receiver on the D-Bus.
---
--- @param interface A string with the interface name.
--- @param func The function to call.
--- @function disconnect_signal
-
--- Emit a signal on the D-Bus.
--- @param bus A string indicating if we are using system or session bus.
--- @param path A string with the dbus path.
--- @param interface A string with the dbus interface.
--- @param method A string with the dbus method name.
--- @param type_1st_arg type of 1st argument
--- @param value_1st_arg value of 1st argument
--- @param type_2nd_arg type of 2nd argument
--- @param value_2nd_arg value of 2nd argument
--- ... etc
--- @function emit_signal

docs/capi/drawable.lua.in

@@ -1,43 +0,0 @@
---- awesome drawable API
--- @author Uli Schlachter <psychon@znc.in>
--- @copyright 2012 Uli Schlachter
--- @release @AWESOME_VERSION@
--- @classmod drawable
-
---- Drawable object.
---
--- @field surface The drawable's cairo surface.
--- @function drawable
-
---- Get drawable geometry. The geometry consists of x, y, width and height.
---
--- @return A table with drawable coordinates and geometry.
--- @function geometry
-
---- Refresh the drawable. When you are drawing to the surface, you have
--- call this function when you are done to make the result visible.
---
--- @function refresh
-
---- Add a signal.
---
--- @param name A signal name.
--- @param func A function to call when the signal is emitted.
--- @function connect_signal
-
---- Remove a signal.
---
--- @param name A signal name.
--- @param func A function to remove.
--- @function disconnect_signal
-
---- Emit a signal.
---
--- @param name A signal name.
--- @param[opt] ... Various arguments.
--- @function emit_signal
-
---- Get the number of instances.
---
--- @return The number of drawable objects alive.
--- @function instances

docs/capi/drawin.lua.in

@@ -1,76 +0,0 @@
---- awesome drawin API
--- @author Julien Danjou <julien@danjou.info>
--- @copyright 2008-2009 Julien Danjou
--- @release @AWESOME_VERSION@
--- @classmod drawin
-
---- Drawin object.
---
--- @field border_width Border width.
--- @field border_color Border color.
--- @field ontop On top of other windows.
--- @field cursor The mouse cursor.
--- @field visible Visibility.
--- @field opacity The opacity of the drawin, between 0 and 1.
--- @field type The window type (desktop, normal, dock, …).
--- @field x The x coordinates.
--- @field y The y coordinates.
--- @field width The width of the drawin.
--- @field height The height of the drawin.
--- @field drawable The drawin's drawable.
--- @field window The X window id.
--- @field shape_bounding The drawin's bounding shape as a (native) cairo surface.
--- @field shape_clip The drawin's clip shape as a (native) cairo surface.
--- @table drawin
-
---- Get or set mouse buttons bindings to a drawin.
---
--- @param buttons_table A table of buttons objects, or nothing.
--- @function buttons
-
---- Get or set drawin struts.
---
--- @param strut A table with new strut, or nothing
--- @return The drawin strut in a table.
--- @function struts
-
---- Get or set drawin geometry. That's the same as accessing or setting the x, y, width or height
--- properties of a drawin.
---
--- @param A table with coordinates to modify.
--- @return A table with drawin coordinates and geometry.
--- @function geometry
-
---- Change a xproperty.
---
--- @param name The name of the X11 property
--- @param value The new value for the property
--- @function set_xproperty
-
---- Get the value of a xproperty.
---
--- @param name The name of the X11 property
--- @function get_xproperty
-
---- Add a signal.
---
--- @param name A signal name.
--- @param func A function to call when the signal is emitted.
--- @function connect_signal
-
---- Remove a signal.
---
--- @param name A signal name.
--- @param func A function to remove.
--- @function disconnect_signal
-
---- Emit a signal.
---
--- @param name A signal name.
--- @param[opt] ... Various arguments.
--- @function emit_signal
-
---- Get the number of instances.
---
--- @return The number of drawin objects alive.
--- @function instances

docs/capi/key.lua.in

@@ -1,39 +0,0 @@
---- awesome key API
--- @author Julien Danjou <julien@danjou.info>
--- @copyright 2008-2009 Julien Danjou
--- @release @AWESOME_VERSION@
--- @classmod key
-
---- Key object.
---
--- @tfield string key The key to trigger an event.
--- @tfield string keysym Same as key, but return the name of the key symbol. It
---   can be identical to key, but for characters like '.' it will return
---   'period'.
--- @tfield table modifiers The modifier key that should be pressed while the
---   key is pressed. An array with all the modifiers. Valid modifiers are: Any,
---   Mod1, Mod2, Mod3, Mod4, Mod5, Shift, Lock and Control.
--- @table key
-
---- Add a signal.
---
--- @tparam string name A signal name.
--- @tparam function func A function to call when the signal is emitted.
--- @function connect_signal
-
---- Remove a signal.
---
--- @tparam string name A signal name.
--- @tparam function func A function to remove.
--- @function disconnect_signal
-
---- Emit a signal.
---
--- @tparam string name A signal name.
--- @param[opt] ... Various arguments.
--- @function emit_signal
-
---- Get the number of instances.
---
--- @treturn number The number of key objects alive.
--- @function instances

docs/capi/keygrabber.lua.in

@@ -1,39 +0,0 @@
---- awesome keygrabber API
--- @author Julien Danjou <julien@danjou.info>
--- @copyright 2008-2009 Julien Danjou
--- @release @AWESOME_VERSION@
--- @module keygrabber
-
----
--- Grab keyboard input and read pressed keys, calling a callback function at
--- each keypress, until `keygrabber.stop` is called.
--- The callback function receives three arguments:
---
--- * a table containing modifiers keys
--- * a string with the pressed key
--- * a string with either "press" or "release" to indicate the event type.
---
--- @param callback A callback function as described above.
--- @function run
--- @usage The following function can be bound to a key, and will be used to
---        resize a client using keyboard.
---
---     function resize(c)
---       keygrabber.run(function(mod, key, event)
---         if event == "release" then return end
---
---         if     key == 'Up'   then awful.client.moveresize(0, 0, 0, 5, c)
---         elseif key == 'Down' then awful.client.moveresize(0, 0, 0, -5, c)
---         elseif key == 'Right' then awful.client.moveresize(0, 0, 5, 0, c)
---         elseif key == 'Left'  then awful.client.moveresize(0, 0, -5, 0, c)
---         else   keygrabber.stop()
---         end
---       end)
---     end
-
---- Stop grabbing the keyboard.
--- @function stop
-
---- Check if the keygrabber is running.
--- @return A boolean value, true if running, false otherwise.
--- @function isrunning

docs/capi/mouse.lua.in

@@ -1,25 +0,0 @@
---- awesome mouse API
--- @author Julien Danjou <julien@danjou.info>
--- @copyright 2008-2009 Julien Danjou
--- @release @AWESOME_VERSION@
--- @module mouse
-
---- Mouse library.
---
--- @field screen Mouse screen number.
--- @table mouse
-
---- A table with X and Y coordinates.
--- @field x X coordinate.
--- @field y Y coordinate.
--- @table coords_table
-
---- Get or set the mouse coords.
--- @tparam coords_table coords_table None or a table with x and y keys as mouse coordinates.
--- @tparam boolean silent Disable mouse::enter or mouse::leave events that could be triggered by the pointer when moving.
--- @treturn coords_table A table with mouse coordinates.
--- @function coords
-
---- Get the client or any object which is under the pointer.
--- @treturn client.client|nil A client or nil.
--- @function object_under_pointer

docs/capi/mousegrabber.lua.in

@@ -1,24 +0,0 @@
---- awesome mousegrabber API
--- @author Julien Danjou <julien@danjou.info>
--- @copyright 2008-2009 Julien Danjou
--- @release @AWESOME_VERSION@
--- @module mousegrabber
-
---- Grab the mouse pointer and list motions, calling callback function at each
--- motion. The callback function must return a boolean value: true to
--- continue grabbing, false to stop.
--- The function is called with one argument:
--- a table containing modifiers pointer coordinates.
---
--- @param func A callback function as described above.
--- @param cursor The name of a X cursor to use while grabbing.
--- @function run
-
---- Stop grabbing the mouse pointer.
---
--- @function stop
-
---- Check if the mousegrabber is running.
---
--- @return A boolean value, true if running, false otherwise.
--- @function isrunning

docs/capi/root.lua.in

@@ -1,51 +0,0 @@
---- awesome root window API
--- @author Julien Danjou <julien@danjou.info>
--- @copyright 2008-2009 Julien Danjou
--- @release @AWESOME_VERSION@
--- @module root
-
---- Get or set global mouse bindings.
--- This binding will be available when you'll click on root window.
---
--- @param button_table An array of mouse button bindings objects, or nothing.
--- @return The array of mouse button bindings objects.
--- @function buttons
-
---- Get or set global key bindings.
--- These binding will be available when you press keys on the root window.
--- @tparam table|nil keys_array An array of key binding objects, or nothing.
--- @return The array of key bindings objects of this client.
--- @function keys
-
---- Set the root cursor.
---
--- @param cursor_name A X cursor name.
--- @function cursor
-
---- Send fake events. Usually the current focused client will get it.
---
--- @param event_type The event type: key_press, key_release, button_press, button_release
---   or motion_notify.
--- @param detail The detail: in case of a key event, this is the keycode to send, in
---   case of a button event this is the number of the button. In case of a
---   motion event, this is a boolean value which if true make the coordinates
---   relatives.
--- @param x In case of a motion event, this is the X coordinate.
--- @param y In case of a motion event, this is the Y coordinate.
--- @function fake_input
-
---- Get the drawins attached to a screen.
---
--- @return A table with all drawins.
--- @function drawins
-
---- Get the wallpaper as a cairo surface or set it as a cairo pattern.
---
--- @param pattern A cairo pattern as light userdata
--- @return A cairo surface or nothing.
--- @function wallpaper
-
---- Get the attached tags.
---
--- @return A table with all tags.
--- @function tags

docs/capi/screen.lua.in

@@ -1,40 +0,0 @@
---- awesome screen API
--- @author Julien Danjou <julien@danjou.info>
--- @copyright 2008-2009 Julien Danjou
--- @release @AWESOME_VERSION@
--- @classmod screen
-
---- Screen is a table where indexes are screen numbers. You can use `screen[1]`
--- to get access to the first screen, etc. Alternatively, if RANDR information
--- is available, you can use output names for finding screen objects.
--- Each screen has a set of properties.
---
--- @tfield table geometry The screen coordinates. Immutable.
--- @tfield table workarea The screen workarea.
--- @tfield int index The screen number.
--- @tfield table outputs If RANDR information is available, a list of outputs
---   for this screen and their size in mm.
--- @table screen
-
---- Get the number of screens.
---
--- @return The screen count, at least 1.
--- @function count
-
---- Add a signal to a screen.
---
--- @string name A signal name.
--- @func func A function to call when the signal is emitted.
--- @function connect_signal
-
---- Remove a signal to a screen.
---
--- @string name A signal name.
--- @func func A function to remove
--- @function disconnect_signal
-
---- Emit a signal to a screen.
---
--- @string name A signal name.
--- @param[opt] ... Various arguments.
--- @function emit_signal

docs/capi/selection.lua.in

@@ -1,10 +0,0 @@
---- awesome selection (clipboard) API
--- @author Julien Danjou <julien@danjou.info>
--- @copyright 2008-2009 Julien Danjou
--- @release @AWESOME_VERSION@
--- @module selection
-
---- Get the selection (clipboard) content.
---
--- @return A string with the selection (clipboard) content.
--- @function selection

docs/capi/tag.lua.in

@@ -1,41 +0,0 @@
---- awesome tag API
--- @author Julien Danjou <julien@danjou.info>
--- @copyright 2008-2009 Julien Danjou
--- @release @AWESOME_VERSION@
--- @classmod tag
-
---- Tag object.
---
--- @field name Tag name.
--- @field selected True if the tag is selected to be viewed.
--- @field activated True if the tag is active and can be used.
--- @table tag
-
---- Get or set the clients attached to this tag.
---
--- @param clients_table None or a table of clients to set as being tagged with this tag.
--- @return A table with the clients attached to this tags.
--- @function clients
-
---- Add a signal.
---
--- @param name A signal name.
--- @param func A function to call when the signal is emitted.
--- @function connect_signal
-
---- Remove a signal.
---
--- @param name A signal name.
--- @param func A function to remove.
--- @function disconnect_signal
-
---- Emit a signal.
---
--- @param name A signal name.
--- @param[opt] ... Various arguments.
--- @function emit_signal
-
---- Get the number of instances.
---
--- @return The number of tag objects alive.
--- @function instances

docs/config.ld

@@ -26,6 +26,8 @@ tparam_alias('client', 'client.client')
 tparam_alias('tag', 'tag')
 -- Should be default, but is not.  Sets up "@tab" => "@tparam table".
 tparam_alias('tab', 'table')
+-- New type for signals
+new_type("signal", "Signals", false, "Arguments")
 
 -- More fitting section names
 kind_names={topic='Documentation', module='Libraries'}
@@ -34,8 +36,19 @@ kind_names={topic='Documentation', module='Libraries'}
 sort_modules=true
 
 file = {
+    -- C parts of libraries
+    '../dbus.c',
+    '../keygrabber.c',
+    '../luaa.c',
+    '../mouse.c',
+    '../mousegrabber.c',
+    '../root.c',
+    '../selection.c',
+    '../spawn.c',
+    '../xkb.c',
+    '../common/luaobject.c',
+    '../objects/',
     -- LUA libraries
-    'capi/',
     '../lib/',
     exclude = {
         -- exclude these modules, as they do not contain any written

keygrabber.c

@@ -19,6 +19,13 @@
  *
  */
 
+/** awesome keygrabber API
+ * @author Julien Danjou <julien@danjou.info>
+ * @copyright 2008-2009 Julien Danjou
+ * @release @AWESOME_VERSION@
+ * @module keygrabber
+ */
+
 #include <unistd.h>
 #include <xkbcommon/xkbcommon.h>
 #include <xkbcommon/xkbcommon-x11.h>
@@ -106,18 +113,31 @@ keygrabber_handlekpress(lua_State *L, xcb_key_press_event_t *e)
     return true;
 }
 
-/** Grab keyboard and read pressed keys, calling callback function at each key
- * press, until keygrabber.stop is called.
- * The function is called with 3 arguments:
- * a table containing modifiers keys, a string with the key pressed and a
- * string with either "press" or "release" to indicate the event type.
+/** Grab keyboard input and read pressed keys, calling a callback function at
+ * each keypress, until `keygrabber.stop` is called.
+ * The callback function receives three arguments:
  *
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
+ * * a table containing modifiers keys
+ * * a string with the pressed key
+ * * a string with either "press" or "release" to indicate the event type.
  *
- * \luastack
+ * @param callback A callback function as described above.
+ * @function run
+ * @usage The following function can be bound to a key, and will be used to
+ *        resize a client using keyboard.
  *
- * \lparam A callback function as described above.
+ *     function resize(c)
+ *       keygrabber.run(function(mod, key, event)
+ *         if event == "release" then return end
+ *
+ *         if     key == 'Up'   then awful.client.moveresize(0, 0, 0, 5, c)
+ *         elseif key == 'Down' then awful.client.moveresize(0, 0, 0, -5, c)
+ *         elseif key == 'Right' then awful.client.moveresize(0, 0, 5, 0, c)
+ *         elseif key == 'Left'  then awful.client.moveresize(0, 0, -5, 0, c)
+ *         else   keygrabber.stop()
+ *         end
+ *       end)
+ *     end
  */
 static int
 luaA_keygrabber_run(lua_State *L)
@@ -137,8 +157,7 @@ luaA_keygrabber_run(lua_State *L)
 }
 
 /** Stop grabbing the keyboard.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
+ * @function stop
  */
 int
 luaA_keygrabber_stop(lua_State *L)
@@ -149,10 +168,8 @@ luaA_keygrabber_stop(lua_State *L)
 }
 
 /** Check if keygrabber is running.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lreturn A boolean value, true if keygrabber is running, false otherwise.
+ * @function isrunning
+ * @treturn bool A boolean value, true if keygrabber is running, false otherwise.
  */
 static int
 luaA_keygrabber_isrunning(lua_State *L)