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/client.lua

@@ -175,8 +175,8 @@ end
 -- @tparam int idx The index: 0 will return first candidate,
 --   1 will return second, etc.
 -- @tparam function filter An optional filter.  If no client is found in the
---         first iteration, client.focus.filter is used by default to get any
+--   first iteration, client.focus.filter is used by default to get any
---         client.
+--   client.
 -- @treturn client.object A client.
 function client.focus.history.get(screen, idx, filter)
     -- When this counter is equal to idx, we return the client

lib/awful/menu.lua

@@ -467,7 +467,7 @@ end
 --- Build a popup menu with running clients and shows it.
 -- @param args Menu table, see new() function for more informations
 -- @param item_args Table that will be merged into each item, see new() for more
---        informations.
+--   informations.
 -- @return The menu.
 function menu.clients(args, item_args)
     local cls = capi.client.get()

lib/awful/mouse/init.lua

@@ -156,8 +156,8 @@ end
 -- @param c The client to move, or the focused one if nil.
 -- @param snap The pixel to snap clients.
 -- @param finished_cb An optional callback function, that will be called
---                 when moving the client has been finished. The client
+--   when moving the client has been finished. The client
---                 that has been moved will be passed to that function.
+--   that has been moved will be passed to that function.
 function mouse.client.move(c, snap, finished_cb)
     local c = c or capi.client.focus
 

lib/awful/rules.lua

@@ -133,7 +133,7 @@ end
 --- Does a given rule entry match a client?
 -- @client c The client.
 -- @tab entry Rule entry (with keys `rule`, `rule_any`, `except` and/or
--- `except_any`).
+--   `except_any`).
 -- @treturn bool
 function rules.matches(c, entry)
     return (rules.match(c, entry.rule) or rules.match_any(c, entry.rule_any)) and
@@ -143,7 +143,7 @@ end
 --- Get list of matching rules for a client.
 -- @client c The client.
 -- @tab _rules The rules to check. List with "rule", "rule_any", "except" and
---             "except_any" keys.
+--   "except_any" keys.
 -- @treturn table The list of matched rules.
 function rules.matching_rules(c, _rules)
     local result = {}

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
@@ -76,11 +84,11 @@ end
 --- Spawn a program and asynchronously and capture its output line by line.
 -- @tparam string|table cmd The command.
 -- @tparam[opt] function stdout_callback Function that is called with each line of
---              output on stdout, e.g. `stdout_callback(line)`.
+--   output on stdout, e.g. `stdout_callback(line)`.
 -- @tparam[opt] function stderr_callback Function that is called with each line of
---              output on stderr, e.g. `stderr_callback(line)`.
+--   output on stderr, e.g. `stderr_callback(line)`.
 -- @tparam[opt] function done_callback Function to call when no more output is
---              produced.
+--   produced.
 -- @treturn[1] Integer the PID of the forked process.
 -- @treturn[2] string Error message.
 function spawn.with_line_callback(cmd, stdout_callback, stderr_callback, done_callback)
@@ -114,9 +122,9 @@ end
 --- Read lines from a Gio input stream
 -- @tparam Gio.InputStream input_stream The input stream to read from.
 -- @tparam function line_callback Function that is called with each line
---         read, e.g. `line_callback(line_from_stream)`.
+--   read, e.g. `line_callback(line_from_stream)`.
 -- @tparam[opt] function done_callback Function that is called when the
---              operation finishes (e.g. due to end of file).
+--   operation finishes (e.g. due to end of file).
 -- @tparam[opt=false] boolean close Should the stream be closed after end-of-file?
 function spawn.read_lines(input_stream, line_callback, done_callback, close)
     local stream = Gio.DataInputStream.new(input_stream)
@@ -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/awful/titlebar.lua

@@ -110,7 +110,7 @@ end
 --- Show a client's titlebar.
 -- @param c The client whose titlebar is modified
 -- @param[opt] position The position of the titlebar. Must be one of "left",
---        "right", "top", "bottom". Default is "top".
+--   "right", "top", "bottom". Default is "top".
 function titlebar.show(c, position)
     local position = position or "top"
     local bars = all_titlebars[c]
@@ -122,7 +122,7 @@ end
 --- Hide a client's titlebar.
 -- @param c The client whose titlebar is modified
 -- @param[opt] position The position of the titlebar. Must be one of "left",
---        "right", "top", "bottom". Default is "top".
+--   "right", "top", "bottom". Default is "top".
 function titlebar.hide(c, position)
     local position = position or "top"
     get_titlebar_function(c, position)(c, 0)
@@ -131,7 +131,7 @@ end
 --- Toggle a client's titlebar, hiding it if it is visible, otherwise showing it.
 -- @param c The client whose titlebar is modified
 -- @param[opt] position The position of the titlebar. Must be one of "left",
---        "right", "top", "bottom". Default is "top".
+--   "right", "top", "bottom". Default is "top".
 function titlebar.toggle(c, position)
     local position = position or "top"
     local drawable, size = get_titlebar_function(c, position)(c)

lib/awful/widget/taglist.lua

@@ -141,9 +141,9 @@ end
 -- @param buttons A table with buttons binding to set.
 -- @param style The style overrides default theme.
 -- @param[opt] update_function Function to create a tag widget on each
---        update. @see awful.widget.common.
+--   update. @see awful.widget.common.
 -- @param[opt] base_widget Optional container widget for tag widgets. Default
---        is wibox.layout.fixed.horizontal().
+--   is wibox.layout.fixed.horizontal().
 -- @param base_widget.bg_focus The background color for focused client.
 -- @param base_widget.fg_focus The foreground color for focused client.
 -- @param base_widget.bg_urgent The background color for urgent clients.

lib/beautiful/init.lua

@@ -113,8 +113,8 @@ end
 
 --- Init function, should be runned at the beginning of configuration file.
 -- @tparam string|table config The theme to load. It can be either the path to
---                      the theme file (returning a table) or directly the table
+--   the theme file (returning a table) or directly the table
---                      containing all the theme values.
+--   containing all the theme values.
 function beautiful.init(config)
     if config then
         local success

lib/gears/cache.lua

@@ -13,7 +13,7 @@ local cache = {}
 
 --- Get an entry from the cache, creating it if it's missing.
 -- @param ... Arguments for the creation callback. These are checked against the
---            cache contents for equality.
+--   cache contents for equality.
 -- @return The entry from the cache
 function cache:get(...)
     local result = self._cache

lib/gears/color.lua

@@ -223,7 +223,7 @@ end
 -- changes could thus have unintended side effects. Use @{create_pattern_uncached}
 -- if you need to modify the returned pattern.
 -- @see create_pattern_uncached, create_solid_pattern, create_png_pattern,
---      create_linear_pattern, create_radial_pattern
+--   create_linear_pattern, create_radial_pattern
 -- @param col The string describing the pattern.
 -- @return a cairo pattern object
 function color.create_pattern(col)

lib/gears/timer.lua

@@ -23,10 +23,9 @@ 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.
+--   started.
 -- @table timer
 
 local timer = { mt = {} }

lib/naughty/core.lua

@@ -189,7 +189,7 @@ end
 --
 -- @param screen Screen to use
 -- @param position top_right | top_left | bottom_right | bottom_left
---             | top_middle | bottom_middle
+--   | top_middle | bottom_middle
 -- @param idx Index of the notification
 -- @param[opt] width Popup width.
 -- @param height Popup height

lib/wibox/hierarchy.lua

@@ -161,9 +161,9 @@ end
 -- @param width The available width for this hierarchy.
 -- @param height The available height for this hierarchy.
 -- @param redraw_callback Callback that is called with the corresponding widget
---        hierarchy on widget::redraw_needed on some widget.
+--   hierarchy on widget::redraw_needed on some widget.
 -- @param layout_callback Callback that is called with the corresponding widget
---        hierarchy on widget::layout_changed on some widget.
+--   hierarchy on widget::layout_changed on some widget.
 -- @param callback_arg A second argument that is given to the above callbacks.
 -- @return A new widget hierarchy
 function hierarchy.new(context, widget, width, height, redraw_callback, layout_callback, callback_arg)
@@ -179,7 +179,7 @@ end
 -- @param height The available height for this hierarchy.
 -- @param[opt] region A region to use for accumulating changed parts
 -- @return A cairo region describing the changed parts (either the `region`
---         argument or a new, internally created region).
+--   argument or a new, internally created region).
 function hierarchy:update(context, widget, width, height, region)
     local region = region or cairo.Region.create()
     hierarchy_update(self, context, widget, width, height, region, self._matrix, self._matrix_to_device)

lib/wibox/init.lua

@@ -55,7 +55,7 @@ end
 -- @param x X coordinate of the point
 -- @param y Y coordinate of the point
 -- @return A sorted table with all widgets that contain the given point. The
---         widgets are sorted by relevance.
+--   widgets are sorted by relevance.
 function wibox:find_widgets(x, y)
     return self._drawable:find_widgets(x, y)
 end

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.
---              remaining space.
+--
--- "outside" - Center widget is sized using its fit function and placed in the
+-- * "inside" - Default option. Size of outside widgets is determined using
---              center of the allowed space. Outside widgets expand (or contract)
+--   their fit function. Second, middle, or center widget expands to fill
---              to fill remaining space on their side.
+--   remaining space.
---    "none" - All widgets are sized using their fit function, drawn to only the
+-- * "outside" - Center widget is sized using its fit function and placed in
---              returned space, or remaining space, whichever is smaller. Center
+--   the center of the allowed space. Outside widgets expand (or contract) to
---              widget gets priority.
+--   fill remaining space on their side.
--- @param mode How to use unused space. "inside" (default) "outside" or "none"
+-- * "none" - All widgets are sized using their fit function, drawn to only the
+--   returned space, or remaining space, whichever is smaller. Center widget
+--   gets priority.
 function align:set_expand(mode)
     if mode == "none" or mode == "outside" then
         self._expand = mode

lib/wibox/widget/base.lua

@@ -187,12 +187,12 @@ end
 -- `:layout()` callback.
 -- @param widget The widget that should be placed.
 -- @param mat A matrix transforming from the parent widget's coordinate
---        system. For example, use matrix.create_translate(1, 2) to draw a
+--   system. For example, use matrix.create_translate(1, 2) to draw a
---        widget at position (1, 2) relative to the parent widget.
+--   widget at position (1, 2) relative to the parent widget.
 -- @param width The width of the widget in its own coordinate system. That is,
---        after applying the transformation matrix.
+--   after applying the transformation matrix.
 -- @param height The height of the widget in its own coordinate system. That is,
---        after applying the transformation matrix.
+--   after applying the transformation matrix.
 -- @return An opaque object that can be returned from :layout()
 function base.place_widget_via_matrix(widget, mat, width, height)
     return {
@@ -209,9 +209,9 @@ end
 -- @param x The x coordinate for the widget.
 -- @param y The y coordinate for the widget.
 -- @param width The width of the widget in its own coordinate system. That is,
---        after applying the transformation matrix.
+--   after applying the transformation matrix.
 -- @param height The height of the widget in its own coordinate system. That is,
---        after applying the transformation matrix.
+--   after applying the transformation matrix.
 -- @return An opaque object that can be returned from :layout()
 function base.place_widget_at(widget, x, y, width, height)
     return base.place_widget_via_matrix(widget, matrix.create_translate(x, y), width, height)

lib/wibox/widget/imagebox.lua

@@ -71,7 +71,7 @@ end
 
 --- Set an imagebox' image
 -- @param image Either a string or a cairo image surface. A string is
---              interpreted as the path to a png image file.
+--   interpreted as the path to a png image file.
 function imagebox:set_image(image)
     local image = image
 
@@ -110,7 +110,7 @@ end
 
 --- Should the image be resized to fit into the available space?
 -- @param allowed If false, the image will be clipped, else it will be resized
---                to fit into the available space.
+--   to fit into the available space.
 function imagebox:set_resize(allowed)
     self.resize_forbidden = not allowed
     self:emit_signal("widget::redraw_needed")
@@ -120,7 +120,7 @@ end
 --- Returns a new imagebox
 -- @param image the image to display, may be nil
 -- @param resize_allowed If false, the image will be clipped, else it will be resized
---                       to fit into the available space.
+--   to fit into the available space.
 local function new(image, resize_allowed)
     local ret = base.make_widget()