From b6d32b136e750af010c69b39d0e268c747f25ffa Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Thu, 28 Aug 2014 19:45:46 +0200 Subject: [PATCH] ldoc: fix usage of @usage, which is automatically --- lib/awful/client.lua.in | 40 ++++++++++---------- lib/awful/keygrabber.lua.in | 33 ++++++++++------- lib/awful/menu.lua.in | 45 +++++++++++----------- lib/awful/prompt.lua.in | 74 +++++++++++++++++++------------------ luadoc/keygrabber.lua | 44 +++++++++++----------- 5 files changed, 122 insertions(+), 114 deletions(-) diff --git a/lib/awful/client.lua.in b/lib/awful/client.lua.in index f71c6fc55..fb4edb7c3 100644 --- a/lib/awful/client.lua.in +++ b/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. +-- @param i The index. Use 1 to get next, -1 to get previous. -- @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 ---

--- local urxvt = function (c)
--- return awful.rules.match(c, {class = "URxvt"})
--- end
---
--- for c in awful.client.iterate(urxvt) do
--- c.minimized = false
--- end
---

+-- @usage +-- -- e.g. to un-minimize all urxvt instances: +-- local urxvt = function (c) +-- return awful.rules.match(c, {class = "URxvt"}) +-- end +-- +-- for c in awful.client.iterate(urxvt) do +-- c.minimized = false +-- end 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 --- ---

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.

+-- 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 ---

--- awful.key({ modkey, }, 'semicolon', function ()
--- local matcher = function (c)
--- return awful.rules.match(c, {class = 'URxvt'})
--- end
+-- @usage +-- -- run or raise urxvt (perhaps, with tabs) on modkey + semicolon +-- awful.key({ modkey, }, 'semicolon', function () +-- local matcher = function (c) +-- return awful.rules.match(c, {class = 'URxvt'}) +-- end -- awful.client.run_or_raise('urxvt', matcher) -- end); ---

function client.run_or_raise(cmd, matcher, merge) local clients = capi.client.get() local findex = util.table.hasitem(clients, capi.client.focus) or 1 diff --git a/lib/awful/keygrabber.lua.in b/lib/awful/keygrabber.lua.in index 3240da786..091dfab3f 100644 --- a/lib/awful/keygrabber.lua.in +++ b/lib/awful/keygrabber.lua.in @@ -45,30 +45,37 @@ function keygrabber.stop(g) end --- --- Grab keyboard and read pressed keys, calling the least callback function from --- stack at each key press, until stack is empty.
+-- Grab keyboard input and read pressed keys, calling the least callback +-- 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.

--- The callback function is passed three 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.

--- A callback can return false to pass the events to the next key grabber in the stack. +-- to the top of the stack. +-- +-- The callback function receives three arguments: +-- +-- +-- A callback can return false 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` --- @usage The following function can be bound to a key, and used to resize a client --- using keyboard. +-- @return the given callback g. +-- @usage +-- -- 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) -- 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) +-- 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 awful.keygrabber.stop(grabber) -- end --- -- end) -- end function keygrabber.run(g) diff --git a/lib/awful/menu.lua.in b/lib/awful/menu.lua.in index 6d3a403ca..eccf3e882 100644 --- a/lib/awful/menu.lua.in +++ b/lib/awful/menu.lua.in @@ -593,30 +593,29 @@ end --
  • Key auto_expand controls the submenu auto expand behaviour by setting it to true (default) or false.
    • -- -- @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 --- a particular rule. Bound to a key, it can for example be used to select from --- dozens of terminals open on several tags. With the use of --- match_any instead of match, menu of clients with --- different classes can also be build. +-- @usage -- The following function builds and shows a menu of clients that match +-- -- a particular rule. +-- -- Bound to a key, it can be used to select from dozens of terminals open on +-- -- several tags. +-- -- When using @{awful.rules.match_any} instead of @{awful.rules.match}, +-- -- a menu of clients with different classes could be build. -- ---

    --- function terminal_menu ()
    ---   terms = {}
    ---   for i, c in pairs(client.get()) do
    ---    if awful.rules.match(c, {class = "URxvt"}) then
    ---     terms[i] =
    ---     {c.name,
    ---     function()
    ---      awful.tag.viewonly(c:tags()[1])
    ---      client.focus = c
    ---     end,
    ---     c.icon
    ---     }
    ---    end
    ---   end
    ---   awful.menu(terms):show()
    --- end
    ---

    +-- function terminal_menu () +-- terms = {} +-- for i, c in pairs(client.get()) do +-- if awful.rules.match(c, {class = "URxvt"}) then +-- terms[i] = +-- {c.name, +-- function() +-- awful.tag.viewonly(c:tags()[1]) +-- client.focus = c +-- end, +-- c.icon +-- } +-- end +-- end +-- awful.menu(terms):show() +-- end function menu.new(args, parent) args = args or {} args.layout = args.layout or wibox.layout.flex.vertical diff --git a/lib/awful/prompt.lua.in b/lib/awful/prompt.lua.in index 8f5e28aa7..6d2e31369 100644 --- a/lib/awful/prompt.lua.in +++ b/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. +--

    The following readline keyboard shortcuts are implemented as expected:

    +-- CTRL+A, CTRL+B, CTRL+C, CTRL+D, +-- CTRL+E, CTRL+J, CTRL+M, CTRL+F, +-- CTRL+H, CTRL+K, CTRL+U, CTRL+W, +-- CTRL+BACKSPACE, SHIFT+INSERT, HOME, +-- END and arrow keys. +--

    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.

    +-- +-- @param args A table with optional arguments: fg_cursor, +-- bg_cursor, ul_cursor, prompt, +-- text, selectall, font, +-- autoexec. -- @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_max Optional parameter: set the maximum entries in history file, 50 by default --- @param done_callback Optional parameter: the callback function to always call without arguments, regardless of whether the prompt was cancelled. --- @param changed_callback Optional parameter: the callback function to call with command as argument when a command was changed. --- @param keypressed_callback Optional parameter: the callback function to call with mod table, key and command as arguments when a key was pressed. --- @usage The following readline keyboard shortcuts are implemented as expected: --- ---
    --- 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 --- +-- @param history_path Optional parameter: file path where the history should be +-- saved, set nil to disable history +-- @param history_max Optional parameter: set the maximum entries in history +-- file, 50 by default +-- @param done_callback Optional parameter: the callback function to always call +-- without arguments, regardless of whether the prompt was cancelled. +-- @param changed_callback Optional parameter: the callback function to call +-- with command as argument when a command was changed. +-- @param keypressed_callback Optional parameter: the callback function to call +-- with mod table, key and command as arguments when a key was pressed. 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() diff --git a/luadoc/keygrabber.lua b/luadoc/keygrabber.lua index 4e2e8bac9..278b82cf3 100644 --- a/luadoc/keygrabber.lua +++ b/luadoc/keygrabber.lua @@ -4,31 +4,33 @@ module("keygrabber") --- --- Grab keyboard and read pressed keys, calling callback function at each key --- press, 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 --- 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 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 --- using keyboard. ---

    --- function resize(c)
    --- keygrabber.run(function(mod, key, event)
    --- if event == "release" then return end

    +-- @usage +-- -- The following function can be bound to a key, and used to resize a client +-- -- using the 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
    ---

    +-- 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. -- @name stop