Document C API directly in the C source code

v2: Add available signals to the docs.

Signed-off-by: Julian Wollrath <jwollrath@web.de>

CMakeLists.txt

@@ -230,7 +230,7 @@ if(GENERATE_DOC)
         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

awesomeConfig.cmake

@@ -288,6 +288,7 @@ file(GLOB_RECURSE awesome_lua_configure_files RELATIVE
     ${SOURCE_DIR}/lib/*.lua
     ${SOURCE_DIR}/themes/*/*.lua)
 set(AWESOME_CONFIGURE_FILES
+    ${awesome_c_configure_files}
     ${awesome_lua_configure_files}
     config.h
     docs/config.ld
@@ -316,5 +317,4 @@ foreach(file ${AWESOME_ADDITIONAL_FILES})
 endforeach()
 #}}}
 
-
 # vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80:foldmethod=marker

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)

luaa.c

@@ -19,6 +19,14 @@
  *
  */
 
+/** awesome core API
+ *
+ * @author Julien Danjou <julien@danjou.info>
+ * @copyright 2008-2009 Julien Danjou
+ * @release @AWESOME_VERSION@
+ * @module awesome
+ */
+
 #define _GNU_SOURCE
 
 #include "luaa.h"
@@ -97,8 +105,7 @@ composite_manager_running(void)
 }
 
 /** Quit awesome.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
+ * @function quit
  */
 static int
 luaA_quit(lua_State *L)
@@ -109,10 +116,9 @@ luaA_quit(lua_State *L)
 
 /** Execute another application, probably a window manager, to replace
  * awesome.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam The command line to execute.
+ *
+ * @param cmd The command line to execute.
+ * @function exec
  */
 static int
 luaA_exec(lua_State *L)
@@ -126,6 +132,7 @@ luaA_exec(lua_State *L)
 }
 
 /** Restart awesome.
+ * @function restart
  */
 static int
 luaA_restart(lua_State *L)
@@ -135,10 +142,10 @@ luaA_restart(lua_State *L)
 }
 
 /** Load an image from a given path.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam The command line to execute.
+ *
+ * @param name The file name.
+ * @return A cairo surface as light user datum.
+ * @function load_image
  */
 static int
 luaA_load_image(lua_State *L)
@@ -196,15 +203,14 @@ luaA_fixups(lua_State *L)
 }
 
 /** awesome global table.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lfield conffile The configuration file which has been loaded.
- * \lfield version The version of awesome.
- * \lfield release The release name of awesome.
- * \lfield startup True if we are still in startup, false otherwise.
- * \lfield startup_errors Error message for errors that occured during startup.
- * \lfield composite_manager_running True if a composite manager is running.
+ * @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
  */
 static int
 luaA_awesome_index(lua_State *L)
@@ -256,11 +262,10 @@ luaA_awesome_index(lua_State *L)
 }
 
 /** Add a global signal.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam A string with the event name.
- * \lparam The function to call.
+ *
+ * @param name A string with the event name.
+ * @param func The function to call.
+ * @function connect_signal
  */
 static int
 luaA_awesome_connect_signal(lua_State *L)
@@ -272,11 +277,10 @@ luaA_awesome_connect_signal(lua_State *L)
 }
 
 /** Remove a global signal.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam A string with the event name.
- * \lparam The function to call.
+ *
+ * @param name A string with the event name.
+ * @param func The function to call.
+ * @function disconnect_signal
  */
 static int
 luaA_awesome_disconnect_signal(lua_State *L)
@@ -290,11 +294,10 @@ luaA_awesome_disconnect_signal(lua_State *L)
 }
 
 /** Emit a global signal.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam A string with the event name.
- * \lparam The function to call.
+ *
+ * @param name A string with the event name.
+ * @param ... The signal arguments.
+ * @function emit_signal
  */
 static int
 luaA_awesome_emit_signal(lua_State *L)
@@ -471,16 +474,49 @@ luaA_init(xdgHandle* xdg)
 
     lua_pop(L, 2); /* pop "package" and "package.loaded" */
 
+    /** A call into the lua code aborted with an error
+     * @signal debug::error
+     */
     signal_add(&global_signals, "debug::error");
+    /** A deprecated lua function was called
+     * @signal debug::deprecation
+     */
     signal_add(&global_signals, "debug::deprecation");
+    /** An invalid key was read from an object (e.g. c.foo)
+     * @signal debug::index::miss
+     */
     signal_add(&global_signals, "debug::index::miss");
+    /** An invalid key was written to an object (e.g. c.foo = "bar")
+     * @signal debug::newindex::miss
+     */
     signal_add(&global_signals, "debug::newindex::miss");
+    /**
+     * @signal systray::update
+     */
     signal_add(&global_signals, "systray::update");
+    /**
+     * @signal wallpaper_changed
+     */
     signal_add(&global_signals, "wallpaper_changed");
+    /**
+     * @signal xkb::map_changed
+     */
     signal_add(&global_signals, "xkb::map_changed");
+    /**
+     * @signal xkb::group_changed
+     */
     signal_add(&global_signals, "xkb::group_changed");
+    /**
+     * @signal refresh
+     */
     signal_add(&global_signals, "refresh");
+    /**
+     * @signal startup
+     */
     signal_add(&global_signals, "startup");
+    /**
+     * @signal exit
+     */
     signal_add(&global_signals, "exit");
 }
 

mouse.c

@@ -19,6 +19,13 @@
  *
  */
 
+/** awesome mouse API
+ * @author Julien Danjou <julien@danjou.info>
+ * @copyright 2008-2009 Julien Danjou
+ * @release @AWESOME_VERSION@
+ * @module mouse
+ */
+
 #include "mouse.h"
 #include "common/util.h"
 #include "globalconf.h"
@@ -26,6 +33,18 @@
 #include "objects/drawin.h"
 #include "objects/screen.h"
 
+/** 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 the pointer position.
  * \param window The window to get position on.
  * \param x will be set to the Pointer-x-coordinate relative to window
@@ -174,8 +193,13 @@ luaA_mouse_pushstatus(lua_State *L, int x, int y, uint16_t mask)
 }
 
 /** Get or set the mouse coords.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
+ *
+ * @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
  */
 static int
 luaA_mouse_coords(lua_State *L)
@@ -212,11 +236,10 @@ luaA_mouse_coords(lua_State *L)
     return luaA_mouse_pushstatus(L, mouse_x, mouse_y, mask);
 }
 
-/** Get the client which is under the pointer.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lreturn A client or nil.
+/** Get the client or any object which is under the pointer.
+ *
+ * @treturn client.client|nil A client or nil.
+ * @function object_under_pointer
  */
 static int
 luaA_mouse_object_under_pointer(lua_State *L)

mousegrabber.c

@@ -19,6 +19,13 @@
  *
  */
 
+/** awesome mousegrabber API
+ * @author Julien Danjou <julien@danjou.info>
+ * @copyright 2008-2009 Julien Danjou
+ * @release @AWESOME_VERSION@
+ * @module mousegrabber
+ */
+
 #include "mousegrabber.h"
 #include "common/xcursor.h"
 #include "mouse.h"
@@ -76,12 +83,9 @@ mousegrabber_handleevent(lua_State *L, int x, int y, uint16_t mask)
  * The function is called with one argument:
  * a table containing modifiers pointer coordinates.
  *
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- *
- * \luastack
- *
- * \lparam A callback function as described above.
+ * @param func A callback function as described above.
+ * @param cursor The name of a X cursor to use while grabbing.
+ * @function run
  */
 static int
 luaA_mousegrabber_run(lua_State *L)
@@ -110,8 +114,8 @@ luaA_mousegrabber_run(lua_State *L)
 }
 
 /** Stop grabbing the mouse pointer.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
+ *
+ * @function stop
  */
 int
 luaA_mousegrabber_stop(lua_State *L)
@@ -122,10 +126,9 @@ luaA_mousegrabber_stop(lua_State *L)
 }
 
 /** Check if mousegrabber is running.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lreturn A boolean value, true if mousegrabber is running, false otherwise.
+ *
+ * @return A boolean value, true if running, false otherwise.
+ * function isrunning
  */
 static int
 luaA_mousegrabber_isrunning(lua_State *L)

objects/button.c

@@ -19,8 +19,36 @@
  *
  */
 
+/** awesome button API
+ *
+ * Furthermore to the classes described here, one can also use signals as
+ * described in @{signals}.
+ *
+ * Some signal names are starting with a dot. These dots are artefacts from
+ * the documentation generation, you get the real signal name by
+ * removing the starting dot.
+ *
+ * @author Julien Danjou <julien@danjou.info>
+ * @copyright 2008-2009 Julien Danjou
+ * @release @AWESOME_VERSION@
+ * @classmod button
+ */
+
 #include "button.h"
 
+/** 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
+ */
+
+/** Get the number of instances.
+ * @treturn int The number of button objects alive.
+ * @function instances
+ */
+
 /** Create a new mouse button bindings.
  * \param L The Lua VM state.
  * \return The number of elements pushed on stack.
@@ -123,9 +151,23 @@ button_class_setup(lua_State *L)
                             (lua_class_propfunc_t) luaA_button_get_modifiers,
                             (lua_class_propfunc_t) luaA_button_set_modifiers);
 
+    /** When bound mouse button + modifiers are pressed.
+     * @param ... One or more arguments are possible
+     * @signal .press
+     */
     signal_add(&button_class.signals, "press");
+    /** When property changes.
+     * @signal property::button
+     */
     signal_add(&button_class.signals, "property::button");
+    /** When property changes.
+     * @signal property::modifiers
+     */
     signal_add(&button_class.signals, "property::modifiers");
+    /** When bound mouse button + modifiers are pressed.
+     * @param ... One or more arguments are possible
+     * @signal .release
+     */
     signal_add(&button_class.signals, "release");
 }
 

objects/client.c

@@ -19,6 +19,21 @@
  *
  */
 
+/** awesome client API
+ *
+ * Furthermore to the classes described here, one can also use signals as
+ * described in @{signals} and X properties as described in @{xproperties}.
+ *
+ * Some signal names are starting with a dot. These dots are artefacts from
+ * the documentation generation, you get the real signal name by
+ * removing the starting dot.
+ *
+ * @author Julien Danjou <julien@danjou.info>
+ * @copyright 2008-2009 Julien Danjou
+ * @release @AWESOME_VERSION@
+ * @classmod client
+ */
+
 #include "objects/client.h"
 #include "common/atoms.h"
 #include "common/xutil.h"
@@ -36,6 +51,75 @@
 #include <xcb/shape.h>
 #include <cairo-xcb.h>
 
+/** 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
+ */
+
+/** 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 the number of instances.
+ *
+ * @return The number of client objects alive.
+ * @function instances
+ */
+
 static area_t titlebar_get_area(client_t *c, client_titlebar_t bar);
 static drawable_t *titlebar_get_drawable(lua_State *L, client_t *c, int cl_idx, client_titlebar_t bar);
 
@@ -1305,11 +1389,10 @@ client_kill(client_t *c)
 }
 
 /** Get all clients into a table.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam An optional screen number.
- * \lreturn A table with all clients.
+ *
+ * @param[opt] screen A screen number.
+ * @return A table with all clients.
+ * @function get
  */
 static int
 luaA_client_get(lua_State *L)
@@ -1332,11 +1415,9 @@ luaA_client_get(lua_State *L)
 }
 
 /** Check if a client is visible on its screen.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lvalue A client.
- * \lreturn A boolean value, true if the client is visible, false otherwise.
+ *
+ * @return A boolean value, true if the client is visible, false otherwise.
+ * @function isvisible
  */
 static int
 luaA_client_isvisible(lua_State *L)
@@ -1433,10 +1514,8 @@ out:
 
 
 /** Kill a client.
- * \param L The Lua VM state.
  *
- * \luastack
- * \lvalue A client.
+ * @function kill
  */
 static int
 luaA_client_kill(lua_State *L)
@@ -1446,11 +1525,9 @@ luaA_client_kill(lua_State *L)
     return 0;
 }
 
-/** Swap a client with another one.
- * \param L The Lua VM state.
- * \luastack
- * \lvalue A client.
- * \lparam A client to swap with.
+/** Swap a client with another one in global client list.
+ * @client A client to swap with.
+ * @function swap
  */
 static int
 luaA_client_swap(lua_State *L)
@@ -1481,10 +1558,11 @@ luaA_client_swap(lua_State *L)
 }
 
 /** Access or set the client tags.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \lparam A table with tags to set, or none to get the current tags table.
- * \return The clients tag.
+ *
+ * @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
  */
 static int
 luaA_client_tags(lua_State *L)
@@ -1534,9 +1612,8 @@ luaA_client_tags(lua_State *L)
 }
 
 /** Raise a client on top of others which are on the same layer.
- * \param L The Lua VM state.
- * \luastack
- * \lvalue A client.
+ *
+ * @function raise
  */
 static int
 luaA_client_raise(lua_State *L)
@@ -1547,9 +1624,8 @@ luaA_client_raise(lua_State *L)
 }
 
 /** Lower a client on bottom of others which are on the same layer.
- * \param L The Lua VM state.
- * \luastack
- * \lvalue A client.
+ *
+ * @function lower
  */
 static int
 luaA_client_lower(lua_State *L)
@@ -1566,10 +1642,8 @@ luaA_client_lower(lua_State *L)
 }
 
 /** Stop managing a client.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lvalue A client.
+ *
+ * @function unmanage
  */
 static int
 luaA_client_unmanage(lua_State *L)
@@ -1783,11 +1857,10 @@ HANDLE_TITLEBAR(bottom, CLIENT_TITLEBAR_BOTTOM)
 HANDLE_TITLEBAR(left, CLIENT_TITLEBAR_LEFT)
 
 /** Return or set client geometry.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam A table with new coordinates, or none.
- * \lreturn A table with client coordinates.
+ *
+ * @param arg1 A table with new coordinates, or none.
+ * @return A table with client coordinates.
+ * @function geometry
  */
 static int
 luaA_client_geometry(lua_State *L)
@@ -1818,14 +1891,13 @@ luaA_client_geometry(lua_State *L)
     return luaA_pusharea(L, c->geometry);
 }
 
-/** Apply size hints to a lua-specified geometry.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam Desired width of client.
- * \lparam Desired height of client.
- * \lreturn Corrected width.
- * \lreturn Corrected height.
+/** 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
+ * @function apply_size_hints
  */
 static int
 luaA_client_apply_size_hints(lua_State *L)
@@ -2310,12 +2382,10 @@ luaA_client_set_shape_clip(lua_State *L, client_t *c)
 }
 
 /** Get or set keys bindings for a client.
- * \param L The Lua VM state.
- * \return The number of element pushed on stack.
- * \luastack
- * \lvalue A client.
- * \lparam An array of key bindings objects, or nothing.
- * \return The array of key bindings objects of this client.
+ *
+ * @param keys_table An array of key bindings objects, or nothing.
+ * @return A table with all keys.
+ * @function keys
  */
 static int
 luaA_client_keys(lua_State *L)
@@ -2570,66 +2640,249 @@ client_class_setup(lua_State *L)
                             (lua_class_propfunc_t) luaA_client_get_client_shape_clip,
                             NULL);
 
+    /** when a client gains focus
+     * @signal .focus
+     */
     signal_add(&client_class.signals, "focus");
+    /** Before manage, after unmanage, and when clients swap.
+     * @signal .list
+     */
     signal_add(&client_class.signals, "list");
+    /**
+     * @signal .manage
+     */
     signal_add(&client_class.signals, "manage");
+    /**
+     * @signal button::press
+     */
     signal_add(&client_class.signals, "button::press");
+    /**
+     * @signal button::release
+     */
     signal_add(&client_class.signals, "button::release");
+    /**
+     * @signal mouse::enter
+     */
     signal_add(&client_class.signals, "mouse::enter");
+    /**
+     * @signal mouse::leave
+     */
     signal_add(&client_class.signals, "mouse::leave");
+    /**
+     * @signal mouse::move
+     */
     signal_add(&client_class.signals, "mouse::move");
+    /**
+     * @signal property::above
+     */
     signal_add(&client_class.signals, "property::above");
+    /**
+     * @signal property::below
+     */
     signal_add(&client_class.signals, "property::below");
+    /**
+     * @signal property::class
+     */
     signal_add(&client_class.signals, "property::class");
+    /**
+     * @signal property::focusable
+     */
     signal_add(&client_class.signals, "property::focusable");
+    /**
+     * @signal property::fullscreen
+     */
     signal_add(&client_class.signals, "property::fullscreen");
+    /**
+     * @signal property::geometry
+     */
     signal_add(&client_class.signals, "property::geometry");
+    /**
+     * @signal property::group_window
+     */
     signal_add(&client_class.signals, "property::group_window");
+    /**
+     * @signal property::height
+     */
     signal_add(&client_class.signals, "property::height");
+    /**
+     * @signal property::hidden
+     */
     signal_add(&client_class.signals, "property::hidden");
+    /**
+     * @signal property::icon
+     */
     signal_add(&client_class.signals, "property::icon");
+    /**
+     * @signal property::icon_name
+     */
     signal_add(&client_class.signals, "property::icon_name");
+    /**
+     * @signal property::instance
+     */
     signal_add(&client_class.signals, "property::instance");
+    /**
+     * @signal property::keys
+     */
     signal_add(&client_class.signals, "property::keys");
+    /**
+     * @signal property::machine
+     */
     signal_add(&client_class.signals, "property::machine");
+    /**
+     * @signal property::maximized
+     */
     signal_add(&client_class.signals, "property::maximized");
+    /**
+     * @signal property::maximized_horizontal
+     */
     signal_add(&client_class.signals, "property::maximized_horizontal");
+    /**
+     * @signal property::maximized_vertical
+     */
     signal_add(&client_class.signals, "property::maximized_vertical");
+    /**
+     * @signal property::minimized
+     */
     signal_add(&client_class.signals, "property::minimized");
+    /**
+     * @signal property::modal
+     */
     signal_add(&client_class.signals, "property::modal");
+    /**
+     * @signal property::name
+     */
     signal_add(&client_class.signals, "property::name");
+    /**
+     * @signal property::ontop
+     */
     signal_add(&client_class.signals, "property::ontop");
+    /**
+     * @signal property::pid
+     */
     signal_add(&client_class.signals, "property::pid");
+    /**
+     * @signal property::role
+     */
     signal_add(&client_class.signals, "property::role");
+    /**
+     * @signal property::screen
+     */
     signal_add(&client_class.signals, "property::screen");
+    /**
+     * @signal property::shape_bounding
+     */
     signal_add(&client_class.signals, "property::shape_bounding");
+    /**
+     * @signal property::shape_client_bounding
+     */
     signal_add(&client_class.signals, "property::shape_client_bounding");
+    /**
+     * @signal property::shape_client_clip
+     */
     signal_add(&client_class.signals, "property::shape_client_clip");
+    /**
+     * @signal property::shape_clip
+     */
     signal_add(&client_class.signals, "property::shape_clip");
+    /**
+     * @signal property::size_hints_honor
+     */
     signal_add(&client_class.signals, "property::size_hints_honor");
+    /**
+     * @signal property::skip_taskbar
+     */
     signal_add(&client_class.signals, "property::skip_taskbar");
+    /**
+     * @signal property::sticky
+     */
     signal_add(&client_class.signals, "property::sticky");
+    /**
+     * @signal property::struts
+     */
     signal_add(&client_class.signals, "property::struts");
+    /**
+     * @signal property::titlebar_bottom
+     */
     signal_add(&client_class.signals, "property::titlebar_bottom");
+    /**
+     * @signal property::titlebar_left
+     */
     signal_add(&client_class.signals, "property::titlebar_left");
+    /**
+     * @signal property::titlebar_right
+     */
     signal_add(&client_class.signals, "property::titlebar_right");
+    /**
+     * @signal property::titlebar_top
+     */
     signal_add(&client_class.signals, "property::titlebar_top");
+    /**
+     * @signal property::transient_for
+     */
     signal_add(&client_class.signals, "property::transient_for");
+    /**
+     * @signal property::type
+     */
     signal_add(&client_class.signals, "property::type");
+    /**
+     * @signal property::urgent
+     */
     signal_add(&client_class.signals, "property::urgent");
+    /**
+     * @signal property::width
+     */
     signal_add(&client_class.signals, "property::width");
+    /**
+     * @signal property::window
+     */
     signal_add(&client_class.signals, "property::window");
+    /**
+     * @signal property::x
+     */
     signal_add(&client_class.signals, "property::x");
+    /**
+     * @signal property::y
+     */
     signal_add(&client_class.signals, "property::y");
+    /**
+     * @signal request::activate
+     */
     signal_add(&client_class.signals, "request::activate");
+    /**
+     * @signal request::fullscreen
+     */
     signal_add(&client_class.signals, "request::fullscreen");
+    /**
+     * @signal request::maximized_horizontal
+     */
     signal_add(&client_class.signals, "request::maximized_horizontal");
+    /**
+     * @signal request::maximized_vertical
+     */
     signal_add(&client_class.signals, "request::maximized_vertical");
+    /**
+     * @signal request::tag
+     */
     signal_add(&client_class.signals, "request::tag");
+    /**
+     * @signal request::urgent
+     */
     signal_add(&client_class.signals, "request::urgent");
+    /** when client is tagged
+     * @signal .tagged
+     */
     signal_add(&client_class.signals, "tagged");
+    /** when a client looses focus
+     * @signal .unfocus
+     */
     signal_add(&client_class.signals, "unfocus");
+    /**
+     * @signal .unmanage
+     */
     signal_add(&client_class.signals, "unmanage");
+    /** when client looses tag
+     * @signal .untagged
+     */
     signal_add(&client_class.signals, "untagged");
 }
 

objects/drawable.c

@@ -20,12 +20,35 @@
  *
  */
 
+/** awesome drawable API
+ *
+ * Furthermore to the classes described here, one can also use signals as
+ * described in @{signals}.
+ *
+ * @author Uli Schlachter <psychon@znc.in>
+ * @copyright 2012 Uli Schlachter
+ * @release @AWESOME_VERSION@
+ * @classmod drawable
+ */
+
 #include "drawable.h"
 #include "common/luaobject.h"
 #include "globalconf.h"
 
 #include <cairo-xcb.h>
 
+/** Drawable object.
+ *
+ * @field surface The drawable's cairo surface.
+ * @function drawable
+ */
+
+/** Get the number of instances.
+ *
+ * @return The number of drawable objects alive.
+ * @function instances
+ */
+
 static lua_class_t drawable_class;
 
 LUA_OBJECT_FUNCS(drawable_class, drawable_t, drawable)
@@ -106,8 +129,8 @@ luaA_drawable_get_surface(lua_State *L, drawable_t *drawable)
 
 /** Refresh a drawable's content. This has to be called whenever some drawing to
  * the drawable's surface has been done and should become visible.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
+ *
+ * @function refresh
  */
 static int
 luaA_drawable_refresh(lua_State *L)
@@ -119,11 +142,10 @@ luaA_drawable_refresh(lua_State *L)
     return 0;
 }
 
-/** Return drawable geometry.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lreturn A table with drawable coordinates.
+/** Get drawable geometry. The geometry consists of x, y, width and height.
+ *
+ * @return A table with drawable coordinates and geometry.
+ * @function geometry
  */
 static int
 luaA_drawable_geometry(lua_State *L)
@@ -160,15 +182,45 @@ drawable_class_setup(lua_State *L)
                             (lua_class_propfunc_t) luaA_drawable_get_surface,
                             NULL);
 
+    /**
+     * @signal button::press
+     */
     signal_add(&drawable_class.signals, "button::press");
+    /**
+     * @signal button::release
+     */
     signal_add(&drawable_class.signals, "button::release");
+    /**
+     * @signal mouse::enter
+     */
     signal_add(&drawable_class.signals, "mouse::enter");
+    /**
+     * @signal mouse::leave
+     */
     signal_add(&drawable_class.signals, "mouse::leave");
+    /**
+     * @signal mouse::move
+     */
     signal_add(&drawable_class.signals, "mouse::move");
+    /**
+     * @signal property::height
+     */
     signal_add(&drawable_class.signals, "property::height");
+    /**
+     * @signal property::width
+     */
     signal_add(&drawable_class.signals, "property::width");
+    /**
+     * @signal property::x
+     */
     signal_add(&drawable_class.signals, "property::x");
+    /**
+     * @signal property::y
+     */
     signal_add(&drawable_class.signals, "property::y");
+    /**
+     * @signal property::surface
+     */
     signal_add(&drawable_class.signals, "property::surface");
 }
 

objects/drawin.c

@@ -20,6 +20,17 @@
  *
  */
 
+/** awesome drawin API
+ *
+ * Furthermore to the classes described here, one can also use signals as
+ * described in @{signals} and X properties as described in @{xproperties}.
+ *
+ * @author Julien Danjou <julien@danjou.info>
+ * @copyright 2008-2009 Julien Danjou
+ * @release @AWESOME_VERSION@
+ * @classmod drawin
+ */
+
 #include "drawin.h"
 #include "common/atoms.h"
 #include "common/xcursor.h"
@@ -32,6 +43,45 @@
 #include <cairo-xcb.h>
 #include <xcb/shape.h>
 
+/** 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 the number of instances.
+ *
+ * @return The number of drawin objects alive.
+ * @function instances
+ */
+
 LUA_OBJECT_FUNCS(drawin_class, drawin_t, drawin)
 
 /** Kick out systray windows.
@@ -313,12 +363,12 @@ luaA_drawin_new(lua_State *L)
     return 1;
 }
 
-/* Set or get the drawin geometry.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam An optional table with drawin geometry.
- * \lreturn The drawin geometry.
+/** 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
  */
 static int
 luaA_drawin_geometry(lua_State *L)
@@ -624,15 +674,45 @@ drawin_class_setup(lua_State *L)
                             (lua_class_propfunc_t) luaA_drawin_get_shape_clip,
                             (lua_class_propfunc_t) luaA_drawin_set_shape_clip);
 
+    /**
+     * @signal property::shape_bounding
+     */
     signal_add(&drawin_class.signals, "property::shape_bounding");
+    /**
+     * @signal property::shape_clip
+     */
     signal_add(&drawin_class.signals, "property::shape_clip");
+    /**
+     * @signal property::border_width
+     */
     signal_add(&drawin_class.signals, "property::border_width");
+    /**
+     * @signal property::cursor
+     */
     signal_add(&drawin_class.signals, "property::cursor");
+    /**
+     * @signal property::height
+     */
     signal_add(&drawin_class.signals, "property::height");
+    /**
+     * @signal property::ontop
+     */
     signal_add(&drawin_class.signals, "property::ontop");
+    /**
+     * @signal property::visible
+     */
     signal_add(&drawin_class.signals, "property::visible");
+    /**
+     * @signal property::width
+     */
     signal_add(&drawin_class.signals, "property::width");
+    /**
+     * @signal property::x
+     */
     signal_add(&drawin_class.signals, "property::x");
+    /**
+     * @signal property::y
+     */
     signal_add(&drawin_class.signals, "property::y");
 }
 

objects/key.c

@@ -20,6 +20,21 @@
  *
  */
 
+/** awesome key API
+ *
+ * Furthermore to the classes described here, one can also use signals as
+ * described in @{signals}.
+ *
+ * Some signal names are starting with a dot. These dots are artefacts from
+ * the documentation generation, you get the real signal name by
+ * removing the starting dot.
+ *
+ * @author Julien Danjou <julien@danjou.info>
+ * @copyright 2008-2009 Julien Danjou
+ * @release @AWESOME_VERSION@
+ * @classmod key
+ */
+
 #include "objects/key.h"
 #include "common/xutil.h"
 #include "xkb.h"
@@ -28,6 +43,24 @@
 #include <X11/Xlib.h>
 #include <xkbcommon/xkbcommon.h>
 
+/** 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
+ */
+
+/** Get the number of instances.
+ *
+ * @return The number of key objects alive.
+ * @function instances
+ */
+
 static void
 luaA_keystore(lua_State *L, int ud, const char *str, ssize_t len)
 {
@@ -235,9 +268,21 @@ key_class_setup(lua_State *L)
                             (lua_class_propfunc_t) luaA_key_get_modifiers,
                             (lua_class_propfunc_t) luaA_key_set_modifiers);
 
+    /**
+     * @signal .press
+     */
     signal_add(&key_class.signals, "press");
+    /**
+     * @signal property::key
+     */
     signal_add(&key_class.signals, "property::key");
+    /**
+     * @signal property::modifiers
+     */
     signal_add(&key_class.signals, "property::modifiers");
+    /**
+     * @signal .release
+     */
     signal_add(&key_class.signals, "release");
 }
 

objects/screen.c

@@ -19,6 +19,17 @@
  *
  */
 
+/** awesome screen API
+ *
+ * Furthermore to the classes described here, one can also use signals as
+ * described in @{signals}.
+ *
+ * @author Julien Danjou <julien@danjou.info>
+ * @copyright 2008-2009 Julien Danjou
+ * @release @AWESOME_VERSION@
+ * @classmod screen
+ */
+
 #include "objects/screen.h"
 #include "banning.h"
 #include "objects/client.h"
@@ -30,6 +41,19 @@
 #include <xcb/xinerama.h>
 #include <xcb/randr.h>
 
+/** 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
+ */
+
 struct screen_output_t
 {
     /** The XRandR names of the output */
@@ -502,12 +526,10 @@ luaA_screen_get_workarea(lua_State *L, screen_t *s)
     return 1;
 }
 
-/** Get the screen count.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
+/** Get the number of screens.
  *
- * \luastack
- * \lreturn The screen count, at least 1.
+ * @return The screen count, at least 1.
+ * @function count
  */
 static int
 luaA_screen_count(lua_State *L)
@@ -557,6 +579,9 @@ screen_class_setup(lua_State *L)
                             NULL,
                             (lua_class_propfunc_t) luaA_screen_get_workarea,
                             NULL);
+    /**
+     * @signal property::workarea
+     */
     signal_add(&screen_class.signals, "property::workarea");
 }
 

objects/tag.c

@@ -19,12 +19,41 @@
  *
  */
 
+/** awesome tag API
+ *
+ * Furthermore to the classes described here, one can also use signals as
+ * described in @{signals}.
+ *
+ * Some signal names are starting with a dot. These dots are artefacts from
+ * the documentation generation, you get the real signal name by
+ * removing the starting dot.
+ *
+ * @author Julien Danjou <julien@danjou.info>
+ * @copyright 2008-2009 Julien Danjou
+ * @release @AWESOME_VERSION@
+ * @classmod tag
+ */
+
 #include "tag.h"
 #include "banning.h"
 #include "client.h"
 #include "ewmh.h"
 #include "luaa.h"
 
+/** 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 the number of instances.
+ *
+ * @return The number of tag objects alive.
+ * @function instances
+ */
+
 /** Tag type */
 struct tag
 {
@@ -179,11 +208,11 @@ luaA_tag_new(lua_State *L)
 }
 
 /** Get or set the clients attached to this tag.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam None or a table of clients to set.
- * \lreturn A table with the clients attached to this tags.
+ *
+ * @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
  */
 static int
 luaA_tag_clients(lua_State *L)
@@ -350,11 +379,29 @@ tag_class_setup(lua_State *L)
                             (lua_class_propfunc_t) luaA_tag_get_activated,
                             (lua_class_propfunc_t) luaA_tag_set_activated);
 
+    /**
+     * @signal property::name
+     */
     signal_add(&tag_class.signals, "property::name");
+    /**
+     * @signal property::selected
+     */
     signal_add(&tag_class.signals, "property::selected");
+    /**
+     * @signal property::activated
+     */
     signal_add(&tag_class.signals, "property::activated");
+    /**
+     * @signal request::select
+     */
     signal_add(&tag_class.signals, "request::select");
+    /**
+     * @signal tagged
+     */
     signal_add(&tag_class.signals, "tagged");
+    /**
+     * @signal untagged
+     */
     signal_add(&tag_class.signals, "untagged");
 }
 

objects/window.c

@@ -19,6 +19,14 @@
  *
  */
 
+/** Handling of X properties.
+ *
+ * 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:get_xproperty(...)` etc.
+ * @classmod xproperties
+ */
+
 #include "objects/window.h"
 #include "common/atoms.h"
 #include "ewmh.h"
@@ -385,9 +393,11 @@ window_get_xproperty(lua_State *L, xcb_window_t window, int prop_idx)
     return 1;
 }
 
-/** Set an xproperty.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
+/** Change a xproperty.
+ *
+ * @param name The name of the X11 property
+ * @param value The new value for the property
+ * @function set_xproperty
  */
 static int
 luaA_window_set_xproperty(lua_State *L)
@@ -396,9 +406,10 @@ luaA_window_set_xproperty(lua_State *L)
     return window_set_xproperty(L, w->window, 2, 3);
 }
 
-/** Get an xproperty.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
+/** Get the value of a xproperty.
+ *
+ * @param name The name of the X11 property
+ * @function get_xproperty
  */
 static int
 luaA_window_get_xproperty(lua_State *L)
@@ -407,7 +418,7 @@ luaA_window_get_xproperty(lua_State *L)
     return window_get_xproperty(L, w->window, 2);
 }
 
-/** Translate a window_type_t into the corresponding EWMH atom.
+/* Translate a window_type_t into the corresponding EWMH atom.
  * @param type The type to return.
  * @return The EWMH atom for this type.
  */
@@ -498,11 +509,29 @@ window_class_setup(lua_State *L)
                             (lua_class_propfunc_t) luaA_window_get_border_width,
                             (lua_class_propfunc_t) luaA_window_set_border_width);
 
+    /**
+     * @signal property::border_color
+     */
     signal_add(&window_class.signals, "property::border_color");
+    /**
+     * @signal property::border_width
+     */
     signal_add(&window_class.signals, "property::border_width");
+    /**
+     * @signal property::buttons
+     */
     signal_add(&window_class.signals, "property::buttons");
+    /**
+     * @signal property::opacity
+     */
     signal_add(&window_class.signals, "property::opacity");
+    /**
+     * @signal property::struts
+     */
     signal_add(&window_class.signals, "property::struts");
+    /**
+     * @signal property::type
+     */
     signal_add(&window_class.signals, "property::type");
 }
 

root.c

@@ -19,6 +19,13 @@
  *
  */
 
+/** awesome root window API
+ * @author Julien Danjou <julien@danjou.info>
+ * @copyright 2008-2009 Julien Danjou
+ * @release @AWESOME_VERSION@
+ * @module root
+ */
+
 #include "globalconf.h"
 
 #include "common/atoms.h"
@@ -133,18 +140,17 @@ _string_to_key_code(const char *s)
     }
 }
 
-/** Send fake events. Usually the current focused client will get it.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam The event type: key_press, key_release, button_press, button_release
- * or motion_notify.
- * \lparam 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.
- * \lparam In case of a motion event, this is the X coordinate.
- * \lparam In case of a motion event, this is the Y coordinate.
- * If not specified, the current one is used.
+/** Send fake events. Usually the currently 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 makes 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
  */
 static int
 luaA_root_fake_input(lua_State *L)
@@ -208,12 +214,11 @@ luaA_root_fake_input(lua_State *L)
 }
 
 /** Get or set global key bindings.
- * This binding will be available when you'll press keys on the root window.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam An array of key bindings objects, or nothing.
- * \lreturn The array of key bindings objects of this client.
+ * These bindings 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
  */
 static int
 luaA_root_keys(lua_State *L)
@@ -250,12 +255,11 @@ luaA_root_keys(lua_State *L)
 }
 
 /** Get or set global mouse bindings.
- * This binding will be available when you'll click on the root window.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam An array of mouse button bindings objects, or nothing.
- * \lreturn The array of mouse button bindings objects.
+ * This binding will be available when you click on the root window.
+ *
+ * @param button_table An array of mouse button bindings objects, or nothing.
+ * @return The array of mouse button bindings objects.
+ * @function buttons
  */
 static int
 luaA_root_buttons(lua_State *L)
@@ -288,10 +292,9 @@ luaA_root_buttons(lua_State *L)
 }
 
 /** Set the root cursor.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam A X cursor name.
+ *
+ * @param cursor_name A X cursor name.
+ * @function cursor
  */
 static int
 luaA_root_cursor(lua_State *L)
@@ -315,10 +318,9 @@ luaA_root_cursor(lua_State *L)
 }
 
 /** Get the drawins attached to a screen.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lreturn A table with all drawins.
+ *
+ * @return A table with all drawins.
+ * @function drawins
  */
 static int
 luaA_root_drawins(lua_State *L)
@@ -334,11 +336,11 @@ luaA_root_drawins(lua_State *L)
     return 1;
 }
 
-/** Get the screen's wallpaper
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lreturn A cairo surface for the wallpaper.
+/** 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
  */
 static int
 luaA_root_wallpaper(lua_State *L)
@@ -398,11 +400,9 @@ luaA_root_wallpaper(lua_State *L)
     return 1;
 }
 
-/** Get the screen's wallpaper
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lreturn A cairo surface for the wallpaper.
+/** Get the attached tags.
+ * @return A table with all tags.
+ * @function tags
  */
 static int
 luaA_root_tags(lua_State *L)

selection.c

@@ -20,6 +20,13 @@
  *
  */
 
+/** awesome selection (clipboard) API
+ * @author Julien Danjou <julien@danjou.info>
+ * @copyright 2008-2009 Julien Danjou
+ * @release @AWESOME_VERSION@
+ * @module selection
+ */
+
 #include "selection.h"
 #include "globalconf.h"
 #include "common/atoms.h"
@@ -28,6 +35,12 @@
 #include <xcb/xcb_atom.h>
 #include <xcb/xcb_event.h>
 
+/** Get the selection (clipboard) content.
+ *
+ * @return A string with the selection (clipboard) content.
+ * @function selection
+ */
+
 static xcb_window_t selection_window = XCB_NONE;
 
 /** Get the current X selection buffer.

spawn.c

@@ -19,6 +19,14 @@
  *
  */
 
+/** awesome core API
+ *
+ * @author Julien Danjou <julien@danjou.info>
+ * @copyright 2008-2009 Julien Danjou
+ * @release @AWESOME_VERSION@
+ * @module awesome
+ */
+
 #include "spawn.h"
 
 #include <unistd.h>
@@ -237,10 +245,30 @@ spawn_init(void)
                                                   spawn_monitor_event,
                                                   NULL, NULL);
 
+    /** For some reason the application aborted startup
+     * @param arg Table which only got the "id" key set
+     * @signal spawn::canceled
+     */
     signal_add(&global_signals, "spawn::canceled");
+    /** When one of the fields from the @{spawn::initiated} table changes
+     * @param arg Table which describes the spawn event
+     * @signal spawn::change
+     */
     signal_add(&global_signals, "spawn::change");
+    /** An application finished starting
+     * @param arg Table which only got the "id" key set
+     * @signal spawn::completed
+     */
     signal_add(&global_signals, "spawn::completed");
+    /** When a new client is beginning to start
+     * @param arg Table which describes the spawn event
+     * @signal spawn::initiated
+     */
     signal_add(&global_signals, "spawn::initiated");
+    /** An application started a spawn event but didn't start in time.
+     * @param arg Table which only got the "id" key set
+     * @signal spawn::timeout
+     */
     signal_add(&global_signals, "spawn::timeout");
 }
 
@@ -310,12 +338,11 @@ parse_command(lua_State *L, int idx, GError **error)
 /** Spawn a program.
  * This function is multi-head (Zaphod) aware and will set display to
  * the right screen according to mouse position.
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack
- * \luastack
- * \lparam The command to launch.
- * \lparam Use startup-notification, true or false, default to true.
- * \lreturn Process ID if everything is OK, or an error string if an error occured.
+ *
+ * @param cmd The command to launch.
+ * @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.
+ * @function spawn
  */
 int
 luaA_spawn(lua_State *L)

xkb.c

@@ -19,17 +19,21 @@
  *
  */
 
+/**
+ * @module awesome
+ */
+
 #include "xkb.h"
 #include "globalconf.h"
 #include <xcb/xkb.h>
 #include <xkbcommon/xkbcommon.h>
 #include <xkbcommon/xkbcommon-x11.h>
 
-/* \brief switch keyboard layout
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lparam layout number, integer from 0 to 3
+/**
+ * Switch keyboard layout.
+ *
+ * @function xkb_set_layout_group
+ * @tparam integer num keyboard layout number, integer from 0 to 3
  */
 int
 luaA_xkb_set_layout_group(lua_State *L)
@@ -40,11 +44,11 @@ luaA_xkb_set_layout_group(lua_State *L)
     return 0;
 }
 
-/* \brief get current layout number
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lreturn current layout number, integer from 0 to 3
+/**
+ * Get current layout number.
+ *
+ * @function xkb_get_layout_group
+ * @treturn integer num Current layout number, integer from 0 to 3.
  */
 int
 luaA_xkb_get_layout_group(lua_State *L)
@@ -65,12 +69,12 @@ luaA_xkb_get_layout_group(lua_State *L)
     return 1;
 }
 
-/* \brief get layout short names
- * \param L The Lua VM state.
- * \return The number of elements pushed on stack.
- * \luastack
- * \lreturn string describing current layout settings, \
- * example: 'pc+us+de:2+inet(evdev)+group(alt_shift_toggle)+ctrl(nocaps)'
+/**
+ * Get layout short names.
+ *
+ * @function xkb_get_group_names
+ * @treturn string A string describing the current layout settings,
+ *   e.g.: 'pc+us+de:2+inet(evdev)+group(alt_shift_toggle)+ctrl(nocaps)'
  */
 int
 luaA_xkb_get_group_names(lua_State *L)