Merge pull request #528 from blueyed/doc-spawn-spawn

Doc fixes: spawn.spawn and long/wrapped lines

Closes https://github.com/awesomeWM/awesome/pull/528.

lib/awful/spawn.lua

@@ -4,6 +4,7 @@
 -- @copyright 2008 Julien Danjou
 -- @copyright 2014 Emmanuel Lepage Vallee
 -- @release @AWESOME_VERSION@
+-- @module awful.spawn
 ---------------------------------------------------------------------------
 
 local capi =
@@ -30,24 +31,31 @@ function spawn.on_snid_callback(c)
     end
 end
 
-
 function spawn.on_snid_cancel(id)
     if spawn.snid_buffer[id] then
         spawn.snid_buffer[id] = nil
     end
 end
 
---- Spawn a program.
+--- Spawn a program, and optionally apply properties and/or run a callback.
--- See awful.rules.execute for more details
+--
--- @param cmd The command.
+-- Applying properties or running a callback requires the program/client to
--- @param sn_rules a property table, false to disable startup-notification.
+-- support startup notifications.
--- @param callback A callback function (if the client support startup notifications)
+--
--- @return The forked PID or an error message
+-- See `awful.rules.execute` for more details about the format of `sn_rules`.
--- @return The startup notification UID, if the spawn was successful
+--
+-- @tparam string|table cmd The command.
+-- @tparam[opt=true] table|boolean sn_rules A table of properties to be applied
+--   after startup; `false` to disable startup notifications.
+-- @tparam[opt] function callback A callback function to be run after startup.
+-- @treturn[1] integer The forked PID.
+-- @treturn[1] string The startup notification ID, if `sn` is not false, or a
+--   `callback` is provided.
+-- @treturn[2] string Error message.
 function spawn.spawn(cmd, sn_rules, callback)
     if cmd and cmd ~= "" then
         local enable_sn = (sn_rules ~= false or callback)
-        enable_sn = not not enable_sn -- Force into a boolean
+        enable_sn = not not enable_sn -- Force into a boolean.
         if not sn_rules and callback then
             sn_rules = {callback=callback}
         elseif callback then
@@ -162,9 +170,10 @@ function spawn.read_lines(input_stream, line_callback, done_callback, close)
     start_read()
 end
 
---- Read a program output and returns its output as a string.
+--- Read a program output and return its output as a string.
--- @param cmd The command to run.
+-- @tparam string cmd The command to run.
--- @return A string with the program output, or the error if one occured.
+-- @treturn string A string with the program output, or the error if one
+--   occured.
 function spawn.pread(cmd)
     if cmd and cmd ~= "" then
         local f, err = io.popen(cmd, 'r')

lib/gears/timer.lua

@@ -23,8 +23,7 @@ local object = require("gears.object")
 -- value. Note that a started timer will not be garbage collected. Call `:stop`
 -- to enable garbage collection.
 -- @tfield number timeout Interval in seconds to emit the timeout signal.
---                        Can be any value, including floating point ones
+--   Can be any value, including floating point ones (e.g. 1.5 seconds).
---                        (e.g. 1.5 seconds).
 -- @tfield boolean started Read-only boolean field indicating if the timer has been
 --   started.
 -- @table timer

lib/wibox/layout/align.lua

@@ -192,17 +192,19 @@ function align:fit(context, orig_width, orig_height)
 end
 
 --- Set the expand mode which determines how sub widgets expand to take up
--- unused space. Options are:
+-- unused space.
---  "inside" - Default option. Size of outside widgets is determined using their
+--
---              fit function. Second, middle, or center widget expands to fill
+-- @tparam[opt=inside] string mode How to use unused space.
+--
+-- * "inside" - Default option. Size of outside widgets is determined using
+--   their fit function. Second, middle, or center widget expands to fill
 --   remaining space.
--- "outside" - Center widget is sized using its fit function and placed in the
+-- * "outside" - Center widget is sized using its fit function and placed in
---              center of the allowed space. Outside widgets expand (or contract)
+--   the center of the allowed space. Outside widgets expand (or contract) to
---              to fill remaining space on their side.
+--   fill remaining space on their side.
---    "none" - All widgets are sized using their fit function, drawn to only the
+-- * "none" - All widgets are sized using their fit function, drawn to only the
---              returned space, or remaining space, whichever is smaller. Center
+--   returned space, or remaining space, whichever is smaller. Center widget
---              widget gets priority.
+--   gets priority.
--- @param mode How to use unused space. "inside" (default) "outside" or "none"
 function align:set_expand(mode)
     if mode == "none" or mode == "outside" then
         self._expand = mode