Docs: general C API fixes

This contains general C API fixes:

    1) Remove module declarations in LUA and use the @module directives

    2) Fix indentation/usage where necessary

Signed-off-by: Ignas Anikevicius (gns_ank) <anikevicius@gmail.com>

luadoc/awesome.lua

@@ -1,74 +1,76 @@
 --- awesome core API
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
-module("awesome")
+-- @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.
--- @class table
--- @name awesome
+-- @table awesome
 
 --- Quit awesome.
--- @name quit
--- @class function
+--
+-- @function quit
 
 --- Execute another application, probably a window manager, to replace
 -- awesome.
+--
 -- @param cmd The command line to execute.
--- @name exec
--- @class function
+-- @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
--- @name load_image
--- @class function
+-- @function load_image
 
 --- Register a new xproperty.
+--
 -- @param name The name of the X11 property
 -- @param type One of "string", "number" or "boolean"
--- @name register_xproperty
--- @class function
+-- @function register_xproperty
 
 --- Change a xproperty.
+--
 -- @param name The name of the X11 property
 -- @param value The new value for the property
--- @name set_xproperty
--- @class function
+-- @function set_xproperty
 
 --- Get the value of a xproperty.
+--
 -- @param name The name of the X11 property
--- @name get_xproperty
--- @class function
+-- @function get_xproperty
 
 --- Add a global signal.
+--
 -- @param name A string with the event name.
 -- @param func The function to call.
--- @name connect_signal
--- @class function
+-- @function connect_signal
 
 --- Remove a global signal.
+--
 -- @param name A string with the event name.
 -- @param func The function to call.
--- @name disconnect_signal
--- @class function
+-- @function disconnect_signal
 
 --- Emit a global signal.
+--
 -- @param name A string with the event name.
 -- @param ... Signal arguments.
--- @name emit_signal
--- @class function
+-- @function emit_signal

luadoc/button.lua

@@ -1,34 +1,30 @@
 --- awesome button API
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
-module("button")
+-- @classmod 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
+--
+-- @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.
--- @class table
--- @name button
+-- @table button
 
 --- Add a signal.
--- @param name A signal name.
--- @param func A function to call when the signal is emitted.
--- @name connect_signal
--- @class function
+-- @tparam string name A signal name.
+-- @tparam func 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.
--- @name disconnect_signal
--- @class function
+-- @tparam string name A signal name.
+-- @tparam func func A function to remove.
+-- @function disconnect_signal
 
 --- Emit a signal.
--- @param name A signal name.
+-- @tparam string name A signal name.
 -- @param ... Various arguments, optional.
--- @name emit_signal
--- @class function
+-- @function emit_signal
 
 --- Get the number of instances.
--- @return The number of button objects alive.
--- @name instances
--- @class function
+-- @treturn int The number of button objects alive.
+-- @function instances

luadoc/client.lua

@@ -1,9 +1,10 @@
 --- awesome client API
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
-module("client")
+-- @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.
@@ -48,25 +49,24 @@ module("client")
 -- @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.
--- @class table
--- @name client
+-- @table client
 
 --- Get all clients into a table.
+--
 -- @param screen An optional screen number.
 -- @return A table with all clients.
--- @name get
--- @class function
+-- @function get
 
 --- Check if a client is visible on its screen.
+--
 -- @return A boolean value, true if the client is visible, false otherwise.
--- @name isvisible
--- @class function
+-- @function isvisible
 
 --- Return client geometry.
+--
 -- @param arg1 A table with new coordinates, or none.
 -- @return A table with client coordinates.
--- @name geometry
--- @class function
+-- @function geometry
 
 --- Apply size hints to a size.
 -- @param width Desired width of client
@@ -77,80 +77,79 @@ module("client")
 -- @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 struts
--- @class function
+-- @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.
--- @name buttons
--- @class function
+-- @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.
--- @name keys
--- @class function
+-- @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.
--- @name tags
--- @class function
+-- @function tags
 
 --- Kill a client.
--- @name kill
--- @class function
+--
+-- @function kill
 
 --- Swap a client with another one in global client list.
 -- @client A client to swap with.
--- @name swap
--- @class function
+-- @function swap
 
 --- Raise a client on top of others which are on the same layer.
--- @name raise
--- @class function
+--
+-- @function raise
 
 --- Lower a client on bottom of others which are on the same layer.
--- @name lower
--- @class function
+--
+-- @function lower
 
 --- Stop managing a client.
--- @name unmanage
--- @class function
+--
+-- @function unmanage
 
 --- Change a xproperty.
+--
 -- @param name The name of the X11 property
 -- @param value The new value for the property
--- @name set_xproperty
--- @class function
+-- @function set_xproperty
 
 --- Get the value of a xproperty.
+--
 -- @param name The name of the X11 property
--- @name get_xproperty
--- @class function
+-- @function get_xproperty
 
 --- Add a signal.
+--
 -- @param name A signal name.
 -- @param func A function to call when the signal is emitted.
--- @name connect_signal
--- @class function
+-- @function connect_signal
 
 --- Remove a signal.
+--
 -- @param name A signal name.
 -- @param func A function to remove.
--- @name disconnect_signal
--- @class function
+-- @function disconnect_signal
 
 --- Emit a signal.
+--
 -- @param name A signal name.
 -- @param ... Various arguments, optional.
--- @name emit_signal
--- @class function
+-- @function emit_signal
 
 --- Get the number of instances.
+--
 -- @return The number of client objects alive.
--- @name instances
--- @class function
+-- @function instances

luadoc/dbus.lua

@@ -1,46 +1,46 @@
 --- awesome D-Bus API
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
-module("dbus")
+-- @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
+-- @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.
--- @name release_name
--- @class function
+-- @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.
--- @name add_match
--- @class function
+-- @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.
--- @name remove_match
--- @class function
+-- @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.
--- @name connect_signal
--- @class function
+-- @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.
--- @name disconnect_signal
--- @class function
+-- @function disconnect_signal
 
 -- Emit a signal on the D-Bus.
 -- @param bus A string indicating if we are using system or session bus.
@@ -52,6 +52,4 @@ module("dbus")
 -- @param type_2nd_arg type of 2nd argument
 -- @param value_2nd_arg value of 2nd argument
 -- ... etc
--- @name emit_signal
--- @class function
---
+-- @function emit_signal

luadoc/drawable.lua

@@ -1,42 +1,42 @@
 --- awesome drawable API
 -- @author Uli Schlachter <psychon@znc.in>
 -- @copyright 2012 Uli Schlachter
-module("drawable")
+-- @classmod drawable
 
 --- Drawable object.
+--
 -- @field surface The drawable's cairo surface.
--- @name drawable
--- @class table
+-- @function drawable
 
 --- Get drawable geometry. The geometry consists of x, y, width and height.
+--
 -- @return A table with drawable coordinates and geometry.
--- @name geometry
--- @class function
+-- @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.
--- @name refresh
--- @class function
+--
+-- @function refresh
 
 --- Add a signal.
+--
 -- @param name A signal name.
 -- @param func A function to call when the signal is emitted.
--- @name connect_signal
--- @class function
+-- @function connect_signal
 
 --- Remove a signal.
+--
 -- @param name A signal name.
 -- @param func A function to remove.
--- @name disconnect_signal
--- @class function
+-- @function disconnect_signal
 
 --- Emit a signal.
+--
 -- @param name A signal name.
 -- @param ... Various arguments, optional.
--- @name emit_signal
--- @class function
+-- @function emit_signal
 
 --- Get the number of instances.
+--
 -- @return The number of drawable objects alive.
--- @name instances
--- @class function
+-- @function instances

luadoc/drawin.lua

@@ -1,9 +1,10 @@
 --- awesome drawin API
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
-module("drawin")
+-- @classmod drawin
 
 --- Drawin object.
+--
 -- @field border_width Border width.
 -- @field border_color Border color.
 -- @field ontop On top of other windows.
@@ -19,57 +20,56 @@ module("drawin")
 -- @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.
--- @class table
--- @name drawin
+-- @table drawin
 
 --- Get or set mouse buttons bindings to a drawin.
+--
 -- @param buttons_table A table of buttons objects, or nothing.
--- @name buttons
--- @class function
+-- @function buttons
 
 --- Get or set drawin struts.
+--
 -- @param strut A table with new strut, or nothing
 -- @return The drawin strut in a table.
--- @name struts
--- @class function
+-- @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.
--- @name geometry
--- @class function
+-- @function geometry
 
 --- Change a xproperty.
+--
 -- @param name The name of the X11 property
 -- @param value The new value for the property
--- @name set_xproperty
--- @class function
+-- @function set_xproperty
 
 --- Get the value of a xproperty.
+--
 -- @param name The name of the X11 property
--- @name get_xproperty
--- @class function
+-- @function get_xproperty
 
 --- Add a signal.
+--
 -- @param name A signal name.
 -- @param func A function to call when the signal is emitted.
--- @name connect_signal
--- @class function
+-- @function connect_signal
 
 --- Remove a signal.
+--
 -- @param name A signal name.
 -- @param func A function to remove.
--- @name disconnect_signal
--- @class function
+-- @function disconnect_signal
 
 --- Emit a signal.
+--
 -- @param name A signal name.
 -- @param ... Various arguments, optional.
--- @name emit_signal
--- @class function
+-- @function emit_signal
 
 --- Get the number of instances.
+--
 -- @return The number of drawin objects alive.
--- @name instances
--- @class function
+-- @function instances

luadoc/key.lua

@@ -1,37 +1,37 @@
 --- awesome key API
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
-module("key")
+-- @classmod 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
+-- @table key
 
 --- Add a signal.
+--
 -- @param name A signal name.
 -- @param func A function to call when the signal is emitted.
--- @name connect_signal
--- @class function
+-- @function connect_signal
 
 --- Remove a signal.
+--
 -- @param name A signal name.
 -- @param func A function to remove.
--- @name disconnect_signal
--- @class function
+-- @function disconnect_signal
 
 --- Emit a signal.
+--
 -- @param name A signal name.
 -- @param ... Various arguments, optional.
--- @name emit_signal
--- @class function
+-- @function emit_signal
 
 --- Get the number of instances.
+--
 -- @return The number of key objects alive.
--- @name instances
--- @class function
+-- @function instances

luadoc/keygrabber.lua

@@ -1,12 +1,11 @@
 --- awesome keygrabber API
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
-module("keygrabber")
+-- @module keygrabber
 
 ---
 -- Grab keyboard input and read pressed keys, calling a callback function at
--- each keypress, until @{keygrabber.stop} is called.
---
+-- each keypress, until `keygrabber.stop` is called.
 -- The callback function receives three arguments:
 -- <ul>
 --   <li>a table containing modifiers keys</li>
@@ -14,11 +13,10 @@ module("keygrabber")
 --   <li>a string with either "press" or "release" to indicate the event type.</li>
 -- </ul>
 -- @param callback A callback function as described above.
--- @name run
--- @class function
--- @usage
--- -- The following function can be bound to a key, and used to resize a client
--- -- using the keyboard.
+-- @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
@@ -33,10 +31,8 @@ module("keygrabber")
 --     end
 
 --- Stop grabbing the keyboard.
--- @name stop
--- @class function
+-- @function stop
 
 --- Check if the keygrabber is running.
 -- @return A boolean value, true if running, false otherwise.
--- @name isrunning
--- @class function
+-- @function isrunning

luadoc/mouse.lua

@@ -1,9 +1,10 @@
 --- awesome mouse API
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
-module("mouse")
+-- @module mouse
 
 --- Mouse library.
+--
 -- @field screen Mouse screen number.
 -- @table mouse
 

luadoc/mousegrabber.lua

@@ -1,23 +1,23 @@
 --- awesome mousegrabber API
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
-module("mousegrabber")
+-- @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.
--- @name run
--- @class function
+-- @function run
 
 --- Stop grabbing the mouse pointer.
--- @name stop
--- @class function
+--
+-- @function stop
 
 --- Check if the mousegrabber is running.
+--
 -- @return A boolean value, true if running, false otherwise.
--- @name isrunning
--- @class function
+-- @function isrunning

luadoc/root.lua

@@ -1,50 +1,50 @@
 --- awesome root window API
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
-module("root")
+-- @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
+-- @function buttons
 
 --- Get or set global key bindings.
 -- These binding will be available when you press keys on the root window.
--- @param keys_array An array of key binding objects, or nothing.
+-- @tparam table|nil keys_array An array of key binding objects, or nothing.
 -- @return The array of key bindings objects of this client.
--- @name keys
--- @class function
+-- @function keys
 
 --- Set the root cursor.
+--
 -- @param cursor_name A X cursor name.
--- @name cursor
--- @class function
+-- @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.
+--   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.
--- @name fake_input
--- @class function
+-- @function fake_input
 
 --- Get the drawins attached to a screen.
+--
 -- @return A table with all drawins.
--- @name drawins
--- @class function
+-- @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.
--- @name wallpaper
--- @class function
+-- @function wallpaper
 
 --- Get the attached tags.
+--
 -- @return A table with all tags.
--- @name tags
--- @class function
+-- @function tags

luadoc/screen.lua

@@ -1,39 +1,39 @@
 --- awesome screen API
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
-module("screen")
+-- @module screen
 
 --- Screen is a table where indexes are screen number. 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.
+--
 -- @field geometry The screen coordinates. Immutable.
 -- @field workarea The screen workarea.
 -- @field index The screen number.
 -- @field outputs If RANDR information is available, a list of outputs for this
 --   screen and their size in mm.
--- @class table
--- @name screen
+-- @table screen
 
 --- Get the number of screen.
+--
 -- @return The screen count, at least 1.
--- @name count
--- @class function
+-- @function count
 
 --- Add a signal to a screen.
+--
 -- @param name A signal name.
 -- @param func A function to call when the signal is emitted.
--- @name connect_signal
--- @class function
+-- @function connect_signal
 
 --- Remove a signal to a screen.
+--
 -- @param name A signal name.
 -- @param func A function to remove
--- @name disconnect_signal
--- @class function
+-- @function disconnect_signal
 
 --- Emit a signal to a screen.
+--
 -- @param name A signal name.
 -- @param ... Various arguments, optional.
--- @name emit_signal
--- @class function
+-- @function emit_signal

luadoc/selection.lua

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

luadoc/tag.lua

@@ -1,40 +1,40 @@
 --- awesome tag API
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
-module("tag")
+-- @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.
--- @class table
--- @name tag
+-- @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.
--- @name clients
--- @class function
+-- @function clients
 
 --- Add a signal.
+--
 -- @param name A signal name.
 -- @param func A function to call when the signal is emitted.
--- @name connect_signal
--- @class function
+-- @function connect_signal
 
 --- Remove a signal.
+--
 -- @param name A signal name.
 -- @param func A function to remove.
--- @name disconnect_signal
--- @class function
+-- @function disconnect_signal
 
 --- Emit a signal.
+--
 -- @param name A signal name.
 -- @param ... Various arguments, optional.
--- @name emit_signal
--- @class function
+-- @function emit_signal
 
 --- Get the number of instances.
+--
 -- @return The number of tag objects alive.
--- @name instances
--- @class function
+-- @function instances