readd proper C API documentation

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

CMakeLists.txt

@@ -21,7 +21,7 @@ include_directories(
     ${AWESOME_REQUIRED_INCLUDE_DIRS}
     ${AWESOME_OPTIONAL_INCLUDE_DIRS})
 
-file(GLOB_RECURSE AWE_LUA_FILES ${BUILD_DIR}/lib/*.lua)
+file(GLOB_RECURSE AWE_LUA_FILES ${BUILD_DIR}/lib/*.lua ${BUILD_DIR}/luadoc/*.lua)
 
 set(AWE_CONF_FILE_DEFAULT ${BUILD_DIR}/awesomerc.lua)
 set(AWE_CONF_FILE rc.lua)
@@ -216,59 +216,24 @@ endif()
 # {{{ Lua API Documentation
 if(GENERATE_LUADOC)
 
-    set(capi_lua ${BUILD_DIR}/lib/capi.lua)
-
     if(NOT BUILD_DIR STREQUAL SOURCE_DIR)
         file(MAKE_DIRECTORY ${BUILD_DIR}/lib)
     endif()
 
-    # {{{ setup a command for ${capi_lua}
-    macro(a_file_match infile regex result_var)
-        file(STRINGS ${infile} match REGEX ${regex} LIMIT_COUNT 1)
-        if(match)
-            set(${result_var} TRUE)
-        else()
-            set(${result_var} FALSE)
-        endif()
-    endmacro()
-
     set(luadoc_c_srcs "")
 
-    # find .c files exporting lua functions
-    foreach(cfile ${AWE_SRCS})
-        a_file_match(${cfile} "const struct luaL_reg" result)
-        if(result)
-            set(luadoc_c_srcs ${luadoc_c_srcs} ${cfile})
-        else()
-            a_file_match(${cfile} "luaA_.*_index" result)
-            if(result)
-                set(luadoc_c_srcs ${luadoc_c_srcs} ${cfile})
-        endif()
-        endif()
-    endforeach()
-
-    # create fake lua source file to process by luadoc
-    add_custom_command(
-        COMMAND ${CAT_EXECUTABLE} ${luadoc_c_srcs}
-                | ${LUA_EXECUTABLE} ${SOURCE_DIR}/build-utils/fake-lua-src.lua
-                > ${capi_lua}
-        OUTPUT  ${capi_lua}
-        DEPENDS ${luadoc_c_srcs}
-        COMMENT "Generating fake lua source."
-        VERBATIM)
-    # }}}
-
     # Generate documentation of lib//0lua
-    file(GLOB_RECURSE lua_lib_files ${BUILD_DIR}/lib/*.lua)
+    file(GLOB_RECURSE lua_lib_files ${BUILD_DIR}/lib/*.lua
+        ${SOURCE_DIR}/luadoc/*.lua)
     foreach(filename ${lua_lib_files})
-        file(RELATIVE_PATH filename ${BUILD_DIR}/lib ${filename})
+        file(RELATIVE_PATH filename ${BUILD_DIR} ${filename})
         set(luadoc_srcs ${luadoc_srcs} ${filename})
     endforeach()
 
     add_custom_target(luadoc ALL
-        COMMAND ${LUADOC_EXECUTABLE} ${luadoc_srcs} -d ${BUILD_DIR}/luadoc
-        WORKING_DIRECTORY ${BUILD_DIR}/lib
-        DEPENDS ${AWE_LUA_FILES} ${capi_lua})
+        COMMAND ${LUADOC_EXECUTABLE} ${luadoc_srcs} -d ${BUILD_DIR}/luadoc --nofiles
+        WORKING_DIRECTORY ${BUILD_DIR}
+        DEPENDS ${AWE_LUA_FILES})
 endif()
 # }}}
 

build-utils/fake-lua-src.lua

@@ -1,111 +0,0 @@
-#!/usr/bin/lua
--- Translate the custom doxygen tags in c-source to a 
--- dummy lua source file that can be processed by luadoc.
--- Take a .c file in stdin
-
-nparam = 0;
-function string.replace_param(s)
-    nparam = nparam + 1;
-    return "@param arg" .. nparam
-end
-
-function string.comment_translate(s)
-    local lua_comment = "";
-    nparam = 0;
-    for line in s:gmatch("[^\r\n]+") do
-        if not line:match("\\lvalue") then
-            line = line:gsub("/%*%*", "---")
-            line = line:gsub("^.*%*", "--")
-            line = line:gsub("\\(lparam)", string.replace_param)
-            line = line:gsub("\\lreturn", "@return")
-            line = line:gsub("\\lfield", "@field")
-            lua_comment = lua_comment .. line .. "\n"
-        end
-    end
-    -- remove last \n
-    lua_comment = lua_comment:sub(1, #lua_comment - 1)
-    return lua_comment
-end
-
--- Read all the files in lines
-lines = io.read("*all")
-
-ilines = {}
-
--- read the lines in table `ilines'
-for line in lines:gmatch("[^\r\n]+") do
-    table.insert(ilines, line)
-end
-
--- Store function documentations in an array
-function_doc = {}
-for i, line in ipairs(ilines) do
-    if line:find("^/%*%*") then
-        comment_start = true
-        comment = line
-    elseif line:find("%*/") then
-        comment_start = false
-        local l = ilines[i + 2]
-        if l then
-            local fctname
-            _, _, fctname = l:find("^(.+)%(lua_State")
-            if fctname then
-                function_doc[fctname] = comment
-            end
-        end
-        comment = nil
-    elseif comment_start then
-        if not line:find("\\param") and not line:find("\\return") and not line:find("\\luastack") then
-            comment = comment .. "\n" .. line
-        end
-    end
-end
-
-print("---------------------------------------------------------------------------")
-print("--- capi: awesome C API")
-print("--")
-print("-- @author Julien Danjou <julien@danjou.info>")
-print("-- @copyright 2008 Julien Danjou")
-print("---------------------------------------------------------------------------")
-print("module(\"capi\")")
-
--- Get function list and print their documentation
-capture = false
-for i, line in ipairs(ilines) do
-    if not libname then
-        _, _, libname, libtype = line:find("const struct luaL_reg awesome_(%a+)_(%a+)%[%] ")
-        -- Special case
-        if not libname then _, _, libname, libtype = line:find("const struct luaL_reg (awesome)_(lib)%[%] =") end
-        -- __index alone
-        if not libname and line:find("^luaA_.*_index") then
-            local fctname, fctdef
-            _, _, fctdef, fctname =  line:find("^(luaA_(.+)_index)")
-            if function_doc[fctdef] and not fctdef:find("_module_") then
-                print(function_doc[fctdef]:comment_translate())
-                print("-- @class table")
-                print("-- @name " .. fctname)
-                print(fctname)
-            end
-        end
-    else
-        if line:find("};") then
-            libname = nil
-        else
-            local fctname, fctdef
-            _, _, fctname, fctdef = line:find("\"(.+)\", (.+) },?")
-            if fctname and (not fctname:find("^__")
-                            or fctname:find("^__call")) then
-                if function_doc[fctdef] then
-                    fctname = "." .. fctname
-                    fctname = fctname:gsub("^.__call", "")
-                    print(function_doc[fctdef]:comment_translate())
-                    print("function " .. libname .. fctname .. "()")
-                    print("end");
-                else
-                    print("This function is not yet documented.")
-                end
-                print()
-            end
-        end
-    end
-end

luadoc/awesome.lua

@@ -0,0 +1,49 @@
+--- awesome core API
+-- @author Julien Danjou <julien@danjou.info>
+-- @copyright 2008-2009 Julien Danjou
+module("awesome")
+
+--- awesome global table.
+-- @field font The default font.
+-- @field font_height The default font height.
+-- @field fg The default foreground color.
+-- @field bg The default background color.
+-- @field version The version of awesome.
+-- #field release The release name of awesome.
+-- @field conffile The configuration file which has been loaded.
+-- @class table
+-- @name awesome
+
+--- Quit awesome.
+-- @param -
+-- @name quit
+-- @class function
+
+--- Execute another application, probably a window manager, to replace
+-- awesome.
+-- @param cmd The command line to execute.
+-- @name exec
+-- @class function
+
+--- Restart awesome.
+-- @param -
+-- @name restart
+-- @class function
+
+--- Add a global signal.
+-- @param name A string with the event name.
+-- @param func The function to call.
+-- @name add_signal
+-- @class function
+
+--- Remove a global signal.
+-- @param name A string with the event name.
+-- @param func The function to call.
+-- @name remove_signal
+-- @class function
+
+--- Emit a global signal.
+-- @param name A string with the event name.
+-- @param ... Signal arguments.
+-- @name emit_signal
+-- @class function

luadoc/button.lua

@@ -0,0 +1,29 @@
+--- awesome button API
+-- @author Julien Danjou <julien@danjou.info>
+-- @copyright 2008-2009 Julien Danjou
+module("button")
+
+--- Button object.
+-- @field button The mouse button number, or 0 for any button.
+-- @field modifiers The modifier key table that should be pressed while the
+-- button is pressed.
+-- @class table
+-- @name button
+
+--- Add a signal.
+-- @param name A signal name.
+-- @param func A function to call when the signal is emited.
+-- @name add_signal
+-- @class function
+
+--- Remove a signal.
+-- @param name A signal name.
+-- @param func A function to remove.
+-- @name remove_signal
+-- @class function
+
+--- Emit a signal.
+-- @param name A signal name.
+-- @param ... Various arguments, optional.
+-- @name emit_signal
+-- @class function

luadoc/client.lua

@@ -0,0 +1,135 @@
+--- awesome client API
+-- @author Julien Danjou <julien@danjou.info>
+-- @copyright 2008-2009 Julien Danjou
+module("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 titlebar The client titlebar.
+-- @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_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_id 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.
+-- @class table
+-- @name client
+
+--- Get all clients into a table.
+-- @param screen An optional screen nunmber.
+-- @return A table with all clients.
+-- @name client.get
+-- @class function
+
+--- Check if a client is visible on its screen.
+-- @param -
+-- @return A boolean value, true if the client is visible, false otherwise.
+-- @name client.isvisible
+-- @class function
+
+--- Return client geometry.
+-- @param arg1 A table with new coordinates, or none.
+-- @return A table with client coordinates.
+-- @name client.geometry
+-- @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.
+-- @name client.struts
+-- @class function
+
+--- 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.
+-- @name client.buttons
+-- @class function
+
+--- 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.
+-- @name client.keys
+-- @class function
+
+--- 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.
+-- @name client.tags
+-- @class function
+
+--- Kill a client.
+-- @param -
+-- @name client.kill
+-- @class function
+
+--- Swap a client with another one in global client list.
+-- @param c A client to swap with.
+-- @name client.swap
+-- @class function
+
+--- Raise a client on top of others which are on the same layer.
+-- @param -
+-- @name client.raise
+-- @class function
+
+--- Lower a client on bottom of others which are on the same layer.
+-- @param -
+-- @name client.lower
+-- @class function
+
+--- Redraw a client by unmapping and mapping it quickly.
+-- @param -
+-- @name client.redraw
+-- @class function
+
+--- Stop managing a client.
+-- @param -
+-- @name client.unmanage
+-- @class function
+
+--- Add a signal.
+-- @param name A signal name.
+-- @param func A function to call when the signal is emited.
+-- @name client.add_signal
+-- @class function
+
+--- Remove a signal.
+-- @param name A signal name.
+-- @param func A function to remove.
+-- @name client.remove_signal
+-- @class function
+
+--- Emit a signal.
+-- @param name A signal name.
+-- @param ... Various arguments, optional.
+-- @name client.emit_signal
+-- @class function

luadoc/dbus.lua

@@ -0,0 +1,43 @@
+--- awesome D-Bus API
+-- @author Julien Danjou <julien@danjou.info>
+-- @copyright 2008-2009 Julien Danjou
+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.
+-- @name request_name
+-- @class function
+
+--- 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.
+-- @name release_name
+-- @class function
+
+--- 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.
+-- @name add_match
+-- @class function
+
+--- 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.
+-- @name remove_match
+-- @class function
+
+--- Add a signal receiver on the D-Bus.
+-- @param interface A string with the interface name.
+-- @param func The function to call.
+-- @name add_signal
+-- @class function
+
+--- Add a signal receiver on the D-Bus.
+-- @param interface A string with the interface name.
+-- @param func The function to call.
+-- @name remove_signal
+-- @class function

luadoc/image.lua

@@ -0,0 +1,130 @@
+--- awesome image API
+-- @author Julien Danjou <julien@danjou.info>
+-- @copyright 2008-2009 Julien Danjou
+module("image")
+
+--- Image objects.
+-- @field width The image width. Immutable.
+-- @field height The image height. Immutable.
+-- @field alpha Boolean indiacating if the image alpha channel is present.
+-- @class table
+-- @name image
+
+--- Performs 90 degree rotations on the current image. Passing 0 orientation does not rotate, 1
+-- rotates clockwise by 90 degree, 2, rotates clockwise by 180 degrees, 3 rotates clockwise by 270
+-- degrees.
+-- @param rotation The rotation to perform.
+-- @name rotate
+-- @class function
+
+--- Rotate an image with specified angle radians and return a new image.
+-- @param angle The angle in radians.
+-- @return A rotated image.
+-- @name rotate
+-- @class function
+
+--- Crop an image to the given rectangle.
+-- @param x The top left x coordinate of the rectangle.
+-- @param y The top left y coordinate of the rectangle.
+-- @param width The width of the rectangle.
+-- @param height The height of the rectangle.
+-- @return A cropped image.
+-- @name crop
+-- @class function
+
+--- Crop the image to the given rectangle and scales it.
+-- @param x The top left x coordinate of the source rectangle.
+-- @param y The top left y coordinate of the source rectangle.
+-- @param width The width of the source rectangle.
+-- @param height The height of the source rectangle.
+-- @param dest_width The width of the destination rectangle.
+-- @param dest_height The height of the destination rectangle.
+-- @param A cropped image.
+-- @name crop_and_scale
+-- @class function
+
+--- Draw a pixel in an image.
+-- @param x The x coordinate of the pixel to draw.
+-- @param y The y coordinate of the pixel to draw.
+-- @param The color to draw the pixel in.
+-- @name draw_pixel
+-- @class function
+
+--- Draw a line in an image.
+-- @param x1 The x1 coordinate of the line to draw.
+-- @param y2 The y1 coordinate of the line to draw.
+-- @param x2 The x2 coordinate of the line to draw.
+-- @param y2 The y2 coordinate of the line to draw.
+-- @param color The color to draw the line in.
+-- @name draw_line
+-- @class function
+
+--- Draw a rectangle in an image.
+-- @param x The x coordinate of the rectangles top left corner.
+-- @param y The y coordinate of the rectangles top left corner.
+-- @param width The width of the rectangle.
+-- @param height The height of the rectangle.
+-- @param fill True to fill the rectangle, false otherwise.
+-- @param color The color to draw the rectangle with.
+-- @name draw_rectangle
+-- @class function
+
+--- Draw a rectangle in an image with gradient color.
+-- @param x The x coordinate of the rectangles top left corner.
+-- @param y The y coordinate of the rectangles top left corner.
+-- @param width The width of the rectangle.
+-- @param height The height of the rectangle.
+-- @param colors A table with the color to draw the rectangle. You can specified the color
+-- distance from the previous one by setting t[color] = distance.
+-- @param angle The angle of the gradient.
+-- @name draw_rectangle_gradient
+-- @class function
+
+--- Draw a circle in an image.
+-- @param x The x coordinate of the center of the circle.
+-- @param y The y coordinate of the center of the circle.
+-- @param width The horizontal amplitude.
+-- @param height The vertical amplitude.
+-- @param fill True if the circle should be filled, false otherwise.
+-- @param color The color to draw the circle with.
+-- @name draw_circle
+-- @class function
+
+--- Saves the image to the given path. The file extension (e.g. .png or .jpg) will affect the
+-- output format.
+-- @param path An image path.
+-- @name save
+-- @class function
+
+--- Insert one image into another.
+-- @param image The image to insert.
+-- @param offset_x The x offset of the image to insert (optional).
+-- @param ofsset_y The y offset of the image to insert (optional).
+-- @param offset_h_up_right The horizontal offset of the upper right image corner (optional).
+-- @param offset_v_up_right The vertical offset of the upper right image corner (optional).
+-- @param offset_h_low_left The horizontal offset of the lower left image corner (optional).
+-- @param offset_v_low_left The vertical offset of the lower left image corner (optional).
+-- @param source_x The x coordinate of the source rectangle (optional).
+-- @param source_y The y coordinate of the source rectangle (optional).
+-- @param source_width The width of the source rectangle (optional).
+-- @param source_height The height of the source rectangle (optional).
+-- @name insert
+-- @class function
+
+--- Add a signal.
+-- @param name A signal name.
+-- @param func A function to call when the signal is emited.
+-- @name add_signal
+-- @class function
+
+--- Remove a signal.
+-- @param name A signal name.
+-- @param func A function to remove.
+-- @name remove_signal
+-- @class function
+
+--- Emit a signal.
+-- @param name A signal name.
+-- @param ... Various arguments, optional.
+-- @name emit_signal
+-- @class function

luadoc/key.lua

@@ -0,0 +1,32 @@
+--- awesome key API
+-- @author Julien Danjou <julien@danjou.info>
+-- @copyright 2008-2009 Julien Danjou
+module("key")
+
+--- Key object.
+-- @field key The key to press to triggers an event.
+-- @field 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'.
+-- @field 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.
+-- @class table
+-- @name key
+
+--- Add a signal.
+-- @param name A signal name.
+-- @param func A function to call when the signal is emited.
+-- @name add_signal
+-- @class function
+
+--- Remove a signal.
+-- @param name A signal name.
+-- @param func A function to remove.
+-- @name remove_signal
+-- @class function
+
+--- Emit a signal.
+-- @param name A signal name.
+-- @param ... Various arguments, optional.
+-- @name emit_signal
+-- @class function

luadoc/keygrabber.lua

@@ -0,0 +1,19 @@
+--- awesome keygrabber API
+-- @author Julien Danjou <julien@danjou.info>
+-- @copyright 2008-2009 Julien Danjou
+module("keygrabber")
+
+--- Grab keyboard and read pressed keys, calling callback function at each key
+-- pressed. The callback function must return a boolean value: true to
+-- continue grabbing, false to stop.
+-- The function is called with 3 arguments:
+-- a table containing modifiers keys, a string with the key pressed and a
+-- string with eithe "press" or "release" to indicate the event type.
+-- @param func A callback function as described above.
+-- @name run
+-- @class function
+
+--- Stop grabbing the keyboard.
+-- @param -
+-- @name stop
+-- @class function

luadoc/mouse.lua

@@ -0,0 +1,22 @@
+--- awesome mouse API
+-- @author Julien Danjou <julien@danjou.info>
+-- @copyright 2008-2009 Julien Danjou
+module("mouse")
+
+--- Mouse library.
+-- @field coords Mouse coordinates.
+-- @field screen Mouse screen number.
+-- @class table
+-- @name mouse
+
+--- Get or set the mouse coords.
+-- @param coords_table None or a table with x and y keys as mouse coordinates.
+-- @return A table with mouse coordinates.
+-- @name coords
+-- @class function
+
+--- Get the client or any object which is under the pointer.
+-- @param -
+-- @return A client or nil.
+-- @name object_under_pointer
+-- @class function

luadoc/mousegrabber.lua

@@ -0,0 +1,18 @@
+--- awesome mousegrabber API
+-- @author Julien Danjou <julien@danjou.info>
+-- @copyright 2008-2009 Julien Danjou
+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.
+-- @name run
+-- @class function
+
+--- Stop grabbing the mouse pointer.
+-- @param -
+-- @name stop
+-- @class function

luadoc/root.lua

@@ -0,0 +1,42 @@
+--- awesome root window API
+-- @author Julien Danjou <julien@danjou.info>
+-- @copyright 2008-2009 Julien Danjou
+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.
+-- @name buttons
+-- @class function
+
+--- Get or set global key bindings.
+-- This binding will be available when you'll press keys on root window.
+-- @param keys_array An array of key bindings objects, or nothing.
+-- @return The array of key bindings objects of this client.
+-- @name keys
+-- @class function
+
+--- Set the root cursor.
+-- @param cursor_name A X cursor name.
+-- @name cursor
+-- @class function
+
+--- 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.
+-- @param screen In case of a motion event, this is the screen number to move on.
+-- If not specified, the current one is used.
+-- @name fake_input
+-- @class function
+
+--- Get the wiboxes attached to a screen.
+-- @param -
+-- @return A table with all wiboxes.
+-- @name wiboxes
+-- @class function

luadoc/screen.lua

@@ -0,0 +1,42 @@
+--- awesome screen API
+-- @author Julien Danjou <julien@danjou.info>
+-- @copyright 2008-2009 Julien Danjou
+module("screen")
+
+--- Scree is a table where indexes are screen number. You can use screen[1] to get acces to the
+-- first screen, etc. Each screen has a set of properties.
+-- @field geometry The screen coordinates. Immutable.
+-- @field workarea The screen workarea.
+-- @field index The screen number.
+-- @class table
+-- @name screen
+
+--- Get the number of screen.
+-- @param -
+-- @return The screen count, at least 1.
+-- @name count
+-- @class function
+
+--- Add a signal to a screen.
+-- @param name A signal name.
+-- @param func A function to call when the signal is emited.
+-- @name add_signal
+-- @class function
+
+--- Remove a signal to a screen.
+-- @param name A signal name.
+-- @param func A function to remove
+-- @name remove_signal
+-- @class function
+
+--- Emit a signal to a screen.
+-- @param name A signal name.
+-- @param ... Various arguments, optional.
+-- @name emit_signal
+-- @class function
+
+--- Get or set screen tags.
+-- @param tags_table None or a table of tags to set to the screen.
+-- The table must contains at least one tag.
+-- @name tags
+-- @class function

luadoc/tag.lua

@@ -0,0 +1,35 @@
+--- awesome tag API
+-- @author Julien Danjou <julien@danjou.info>
+-- @copyright 2008-2009 Julien Danjou
+module("tag")
+
+--- Tag object.
+-- @field name Tag name.
+-- @field screen Screen number of the tag.
+-- @field selected True if the client is selected to be viewed.
+-- @class table
+-- @name 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.
+-- @name clients
+-- @class function
+
+--- Add a signal.
+-- @param name A signal name.
+-- @param func A function to call when the signal is emited.
+-- @name add_signal
+-- @class function
+
+--- Remove a signal.
+-- @param name A signal name.
+-- @param func A function to remove.
+-- @name remove_signal
+-- @class function
+
+--- Emit a signal.
+-- @param name A signal name.
+-- @param ... Various arguments, optional.
+-- @name emit_signal
+-- @class function

luadoc/wibox.lua

@@ -0,0 +1,65 @@
+--- awesome wibox API
+-- @author Julien Danjou <julien@danjou.info>
+-- @copyright 2008-2009 Julien Danjou
+module("wibox")
+
+--- Wibox object.
+-- @field screen Screen number.
+-- @field client The client attached to (titlebar only).
+-- @field border_width Border width.
+-- @field border_color Border color.
+-- @field align The alignment (titlebar only).
+-- @field fg Foreground color.
+-- @field bg Background color.
+-- @field bg_image Background image.
+-- @field position The position (titlebar only).
+-- @field ontop On top of other windows.
+-- @field cursor The mouse cursor.
+-- @field visible Visibility.
+-- @field orientation The drawing orientation: east, north or south.
+-- @field widgets A table with all widgets drawn on this wibox.
+-- @field opacity The opacity of the wibox, between 0 and 1.
+-- @field x The x coordinates.
+-- @field y The y coordinates.
+-- @field width The width of the wibox.
+-- @field height The height of the wibox.
+-- @field shape_bounding Image describing the window's border shape.
+-- @field shape_clip Image describing the window's content shape.
+-- @class table
+-- @name wibox
+
+--- Get or set mouse buttons bindings to a wibox.
+-- @param buttons_table A table of buttons objects, or nothing.
+-- @name buttons
+-- @class function
+
+--- Get or set wibox struts.
+-- @param strut A table with new strut, or nothing
+-- @return The wibox strut in a table.
+-- @name struts
+-- @class function
+
+--- Get or set wibox geometry. That's the same as accessing or setting the x, y, width or height
+-- properties of a wibox.
+-- @param A table with coordinates to modify.
+-- @return A table with wibox coordinates and geometry.
+-- @name geometry
+-- @class function
+
+--- Add a signal.
+-- @param name A signal name.
+-- @param func A function to call when the signal is emited.
+-- @name add_signal
+-- @class function
+
+--- Remove a signal.
+-- @param name A signal name.
+-- @param func A function to remove.
+-- @name remove_signal
+-- @class function
+
+--- Emit a signal.
+-- @param name A signal name.
+-- @param ... Various arguments, optional.
+-- @name emit_signal
+-- @class function

luadoc/widget.lua

@@ -0,0 +1,68 @@
+--- awesome widget API
+-- @author Julien Danjou <julien@danjou.info>
+-- @copyright 2008-2009 Julien Danjou
+module("widget")
+
+--- Generic widget.
+-- @field visible The widget visibility.
+-- @field type The widget type. Can only be set using constructor. Type can be either textbox,
+-- imagebox or systray.
+-- @class table
+-- @name widget
+
+--- Set the widget buttons. It will receive a press or release event when of this buttons is
+-- pressed.
+-- @param buttons_table A table with buttons, or nil if you do not want to modify it.
+-- @return A table with buttons the widget is listening to.
+-- @name buttons
+-- @class function
+
+--- Get the widget extents, i.e., the size the widgets needs to be drawn.
+-- @param -
+-- @return A table with x, y, width and height.
+-- @name extents
+-- @class function
+
+--- Textbox widgets.
+-- @field text The text to display.
+-- @field width The width of the textbox. Set to 0 for auto.
+-- @field wrap The wrap mode: word, char, word_char.
+-- @field ellipsize The ellipsize mode: start, middle or end.
+-- @field border_width The border width to draw around.
+-- @field border_color The border color.
+-- @field align Text alignment, left, center or right.
+-- @field margin Method to pass text margin: a table with top, left, right and bottom keys.
+-- @field bg Background color.
+-- @field bg_image Background image.
+-- @field bg_align Background image alignment, left, center, right, bottom, top or middle
+-- @field bg_resize Background resize.
+-- @class table
+-- @name textbox
+
+--- Imagebox widget.
+-- @field image The image to display.
+-- @field bg The background color to use.
+-- @class table
+-- @name imagebox
+
+--- Systray widget.
+-- @class table
+-- @name systray
+
+--- Add a signal.
+-- @param name A signal name.
+-- @param func A function to call when the signal is emited.
+-- @name add_signal
+-- @class function
+
+--- Remove a signal.
+-- @param name A signal name.
+-- @param func A function to remove.
+-- @name remove_signal
+-- @class function
+
+--- Emit a signal.
+-- @param name A signal name.
+-- @param ... Various arguments, optional.
+-- @name emit_signal
+-- @class function