Merge branch 'fix-ldoc-usage' of git://github.com/blueyed/awesome

lib/awful/client.lua.in

@@ -235,8 +235,7 @@ function client.tiled(screen)
 end
 
 --- Get a client by its relative index to the focused window.
--- @usage Set i to 1 to get next, -1 to get previous.
+-- @param i The index. Use 1 to get next, -1 to get previous.
--- @param i The index.
 -- @param c Optional client.
 -- @return A client, or nil if no client is available.
 function client.next(i, c)
@@ -928,16 +927,15 @@ end
 -- index of the currently focused client.
 -- @param s      which screen to use.  nil means all screens.
 --
--- @usage e.g.: un-minimize all urxvt instances
+-- @usage
--- <p><code>
+-- -- e.g. to un-minimize all urxvt instances:
--- local urxvt = function (c) <br/>
+-- local urxvt = function (c)
---   return awful.rules.match(c, {class = "URxvt"}) <br/>
+--   return awful.rules.match(c, {class = "URxvt"})
--- end <br/>
+-- end
--- </br>
+--
--- for c in awful.client.iterate(urxvt) do <br/>
+-- for c in awful.client.iterate(urxvt) do
---   c.minimized = false <br/>
+--   c.minimized = false
--- end <br/>
+-- end
--- </code></p>
 function client.iterate(filter, start, s)
     local clients = capi.client.get(s)
     local focused = capi.client.focus
@@ -946,23 +944,23 @@ function client.iterate(filter, start, s)
 end
 
 ---
--- <p>Switch to a client matching the given condition if running, else spawn it.
+-- Switch to a client matching the given condition if running, else spawn it.
+--
 -- If multiple clients match the given condition then the next one is
--- focussed.</p>
+-- focussed.
 --
 -- @param cmd     the command to execute
 -- @param matcher a function that returns true to indicate a matching client
 -- @param merge   if true then merge tags when clients are not visible
 --
--- @usage run or raise urxvt (perhaps, with tabs) on modkey + semicolon
+-- @usage
--- <p><code>
+-- -- run or raise urxvt (perhaps, with tabs) on modkey + semicolon
--- awful.key({ modkey, }, 'semicolon', function ()            <br/>
+-- awful.key({ modkey, }, 'semicolon', function ()
---   local matcher = function (c)                             <br/>
+--   local matcher = function (c)
---     return awful.rules.match(c, {class = 'URxvt'}) <br/>
+--     return awful.rules.match(c, {class = 'URxvt'})
---   end                                                      <br/>
+--   end
 --   awful.client.run_or_raise('urxvt', matcher)
 -- end);
--- </code></p>
 function client.run_or_raise(cmd, matcher, merge)
     local clients = capi.client.get()
     local findex  = util.table.hasitem(clients, capi.client.focus) or 1

lib/awful/keygrabber.lua.in

@@ -45,18 +45,26 @@ function keygrabber.stop(g)
 end
 
 ---
--- Grab keyboard and read pressed keys, calling the least callback function from
+-- Grab keyboard input and read pressed keys, calling the least callback
--- stack at each  key press, until stack is empty. </br>
+-- function from the stack at each keypress, until the stack is empty.
+--
 -- Calling run with the same callback again will bring the callback
--- to the top of the stack. </br></br>
+-- to the top of the stack.
--- The callback function is passed three arguments: </br>
+--
--- a table containing modifiers keys, a string with the key pressed and a
+-- The callback function receives three arguments:
--- string with either "press" or "release" to indicate the event type.</br></br>
+-- <ul>
--- A callback can return false to pass the events to the next key grabber in the stack.
+--   <li>a table containing modifiers keys</li>
+--   <li>a string with the pressed key</li>
+--   <li>a string with either "press" or "release" to indicate the event type</li>
+-- </ul>
+--
+-- A callback can return <code>false</code> to pass the events to the next
+-- keygrabber in the stack.
 -- @param g The key grabber callback that will get the key events until it will be deleted or a new grabber is added.
--- @return the given callback `g`
+-- @return the given callback <code>g</code>.
--- @usage The following function can be bound to a key, and used to resize a client
+-- @usage
--- using keyboard.
+-- -- The following function can be bound to a key, and be used to resize a
+-- -- client using the keyboard.
 --
 -- function resize(c)
 --   local grabber = awful.keygrabber.run(function(mod, key, event)
@@ -68,7 +76,6 @@ end
 --     elseif key == 'Left'  then awful.client.moveresize(0, 0, -5, 0, c)
 --     else   awful.keygrabber.stop(grabber)
 --     end
---
 --   end)
 -- end
 function keygrabber.run(g)

lib/awful/menu.lua.in

@@ -593,30 +593,29 @@ end
 -- <li> Key auto_expand controls the submenu auto expand behaviour by setting it to true (default) or false. </li>
 -- </ul>
 -- @param parent Specify the parent menu if we want to open a submenu, this value should never be set by the user.
--- @usage The following function builds, and shows a menu of clients that match
+-- @usage -- The following function builds and shows a menu of clients that match
--- a particular rule. Bound to a key, it can for example be used to select from
+-- -- a particular rule.
--- dozens of terminals open on several tags. With the use of
+-- -- Bound to a key, it can be used to select from dozens of terminals open on
--- <code>match_any</code> instead of <code>match</code>, menu of clients with
+-- -- several tags.
--- different classes can also be build.
+-- -- When using @{awful.rules.match_any} instead of @{awful.rules.match},
+-- -- a menu of clients with different classes could be build.
 --
--- <p><code>
+-- function terminal_menu ()
---                     function terminal_menu ()                           <br/>
+--   terms = {}
--- &nbsp;                terms = {}                                        <br/>
+--   for i, c in pairs(client.get()) do
--- &nbsp;                for i, c in pairs(client.get()) do                <br/>
+--     if awful.rules.match(c, {class = "URxvt"}) then
--- &nbsp;&nbsp;            if awful.rules.match(c, {class = "URxvt"}) then <br/>
+--       terms[i] =
--- &nbsp;&nbsp;&nbsp;        terms[i] =                                    <br/>
+--         {c.name,
--- &nbsp;&nbsp;&nbsp;          {c.name,                                    <br/>
+--          function()
--- &nbsp;&nbsp;&nbsp;           function()                                 <br/>
+--            awful.tag.viewonly(c:tags()[1])
--- &nbsp;&nbsp;&nbsp;&nbsp;       awful.tag.viewonly(c:tags()[1])          <br/>
+--            client.focus = c
--- &nbsp;&nbsp;&nbsp;&nbsp;       client.focus = c                         <br/>
+--          end,
--- &nbsp;&nbsp;&nbsp;           end,                                       <br/>
+--          c.icon
--- &nbsp;&nbsp;&nbsp;           c.icon                                     <br/>
+--         }
--- &nbsp;&nbsp;&nbsp;          }                                           <br/>
+--     end
--- &nbsp;&nbsp;            end                                             <br/>
+--   end
--- &nbsp;                end                                               <br/>
+--   awful.menu(terms):show()
--- &nbsp;                awful.menu(terms):show()                          <br/>
+-- end
---                     end                                                 <br/>
---</code></p>
 function menu.new(args, parent)
     args = args or {}
     args.layout = args.layout or wibox.layout.flex.vertical

lib/awful/prompt.lua.in

@@ -157,44 +157,46 @@ local function prompt_text_with_cursor(args)
 end
 
 --- Run a prompt in a box.
--- @param args A table with optional arguments: fg_cursor, bg_cursor, ul_cursor, prompt, text, selectall, font, autoexec.
+-- <p>The following readline keyboard shortcuts are implemented as expected:</p>
+-- <kbd>CTRL+A</kbd>, <kbd>CTRL+B</kbd>, <kbd>CTRL+C</kbd>, <kbd>CTRL+D</kbd>,
+-- <kbd>CTRL+E</kbd>, <kbd>CTRL+J</kbd>, <kbd>CTRL+M</kbd>, <kbd>CTRL+F</kbd>,
+-- <kbd>CTRL+H</kbd>, <kbd>CTRL+K</kbd>, <kbd>CTRL+U</kbd>, <kbd>CTRL+W</kbd>,
+-- <kbd>CTRL+BACKSPACE</kbd>, <kbd>SHIFT+INSERT</kbd>, <kbd>HOME</kbd>,
+-- <kbd>END</kbd> and arrow keys.
+-- <p>The following shortcuts implement additional history manipulation commands
+-- where the search term is defined as the substring of the command from first
+-- character to cursor position.</p>
+-- <ul>
+-- <li><code>CTRL+R</code>: reverse history search, matches any history entry
+-- containing search term.</li>
+-- <li><code>CTRL+S</code>: forward history search, matches any history entry
+-- containing search term.</li>
+-- <li><code>CTRL+UP</code>: ZSH up line or search, matches any history entry
+-- starting with search term.</li>
+-- <li><code>CTRL+DOWN</code>: ZSH down line or search, matches any history
+-- entry starting with search term.</li>
+-- <li><code>CTRL+DELETE</code>: delete the currently visible history entry from
+-- history file.
+-- This does not delete new commands or history entries under user editing.</li>
+-- </ul>
+-- @param args A table with optional arguments: <code>fg_cursor</code>,
+-- <code>bg_cursor</code>, <code>ul_cursor</code>, <code>prompt</code>,
+-- <code>text</code>, <code>selectall</code>, <code>font</code>,
+-- <code>autoexec</code>.
 -- @param textbox The textbox to use for the prompt.
--- @param exe_callback The callback function to call with command as argument when finished.
+-- @param exe_callback The callback function to call with command as argument
+-- when finished.
 -- @param completion_callback The callback function to call to get completion.
--- @param history_path Optional parameter: file path where the history should be saved, set nil to disable history
+-- @param history_path Optional parameter: file path where the history should be
--- @param history_max Optional parameter: set the maximum entries in history file, 50 by default
+-- saved, set nil to disable history
--- @param done_callback Optional parameter: the callback function to always call without arguments, regardless of whether the prompt was cancelled.
+-- @param history_max Optional parameter: set the maximum entries in history
--- @param changed_callback Optional parameter: the callback function to call with command as argument when a command was changed.
+-- file, 50 by default
--- @param keypressed_callback Optional parameter: the callback function to call with mod table, key and command as arguments when a key was pressed.
+-- @param done_callback Optional parameter: the callback function to always call
--- @usage The following readline keyboard shortcuts are implemented as expected:
+-- without arguments, regardless of whether the prompt was cancelled.
--- <ul>
+-- @param changed_callback Optional parameter: the callback function to call
--- <li><code>CTRL+A</code></li>
+-- with command as argument when a command was changed.
--- <li><code>CTRL+B</code></li>
+-- @param keypressed_callback Optional parameter: the callback function to call
--- <li><code>CTRL+C</code></li>
+-- with mod table, key and command as arguments when a key was pressed.
--- <li><code>CTRL+D</code></li>
--- <li><code>CTRL+E</code></li>
--- <li><code>CTRL+J</code></li>
--- <li><code>CTRL+M</code></li>
--- <li><code>CTRL+F</code></li>
--- <li><code>CTRL+H</code></li>
--- <li><code>CTRL+K</code></li>
--- <li><code>CTRL+U</code></li>
--- <li><code>CTRL+W</code></li>
--- <li><code>CTRL+BASKPACE</code></li>
--- <li><code>SHIFT+INSERT</code></li>
--- <li><code>HOME</code></li>
--- <li><code>END</code></li>
--- <li>arrow keys</li>
--- </ul>
--- <br/>
--- The following shortcuts implement additional history manipulation commands where the search term is defined as the substring of command from first character to cursor position
--- <ul>
--- <li><code>CTRL+R</code>: reverse history search, matches any history entry containing search term</li>
--- <li><code>CTRL+S</code>: forward history search, matches any history entry containing search term</li>
--- <li><code>CTRL+UP</code>: ZSH up line or search, matches any history entry starting with search term</li>
--- <li><code>CTRL+DOWN</code>: ZSH down line or search, matches any history entry starting with search term</li>
--- <li><code>CTRL+DELETE</code>: delete the currently visible history entry from history file. <br/>Does not delete new commands or history entries under user editing</li>
--- </ul>
 function prompt.run(args, textbox, exe_callback, completion_callback, history_path, history_max, done_callback, changed_callback, keypressed_callback)
     local grabber
     local theme = beautiful.get()

luadoc/keygrabber.lua

@@ -4,31 +4,33 @@
 module("keygrabber")
 
 ---
--- Grab keyboard and read pressed keys, calling callback function at each key
+-- Grab keyboard input and read pressed keys, calling a callback function at
--- press, until keygrabber.stop is called.
+-- each keypress, until @{keygrabber.stop} is called.
--- The callback function is passed three arguments:
+--
--- a table containing modifiers keys, a string with the key pressed and a
+-- The callback function receives three arguments:
--- string with either "press" or "release" to indicate the event type.
+-- <ul>
+--   <li>a table containing modifiers keys</li>
+--   <li>a string with the pressed key</li>
+--   <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 Following function can be bound to a key, and used to resize a client
+-- @usage
--- using keyboard.
+-- -- The following function can be bound to a key, and used to resize a client
--- <p><code>
+-- -- using the keyboard.
--- function resize(c) <br/>
+-- function resize(c)
---   keygrabber.run(function(mod, key, event) </br>
+--   keygrabber.run(function(mod, key, event)
---     if event == "release" then return end </br></br>
+--     if event == "release" then return end
 --
---     if     key == 'Up'   then awful.client.moveresize(0, 0, 0, 5, c) <br/>
+--     if     key == 'Up'    then awful.client.moveresize(0, 0, 0, 5, c)
---     elseif key == 'Down' then awful.client.moveresize(0, 0, 0, -5, c) <br/>
+--     elseif key == 'Down'  then awful.client.moveresize(0, 0, 0, -5, c)
---     elseif key == 'Right' then awful.client.moveresize(0, 0, 5, 0, c) <br/>
+--     elseif key == 'Right' then awful.client.moveresize(0, 0, 5, 0, c)
---     elseif key == 'Left'  then awful.client.moveresize(0, 0, -5, 0, c) <br/>
+--     elseif key == 'Left'  then awful.client.moveresize(0, 0, -5, 0, c)
---     else   keygrabber.stop() <br/>
+--     else   keygrabber.stop()
---     end <br/><br/>
+--     end
---
+--   end)
---   end) <br/>
+-- end
--- end <br/>
--- </code></p>
 
 --- Stop grabbing the keyboard.
 -- @name stop