diff --git a/docs/capi/button.lua.in b/docs/capi/button.lua.in
index 2d6b7985d..7c0c8beda 100644
--- a/docs/capi/button.lua.in
+++ b/docs/capi/button.lua.in
@@ -23,7 +23,7 @@
 
 --- Emit a signal.
 -- @tparam string name A signal name.
--- @param ... Various arguments, optional.
+-- @param[opt] ... Various arguments.
 -- @function emit_signal
 
 --- Get the number of instances.
diff --git a/docs/capi/client.lua.in b/docs/capi/client.lua.in
index 4464425d6..522c54e40 100644
--- a/docs/capi/client.lua.in
+++ b/docs/capi/client.lua.in
@@ -54,7 +54,7 @@
 
 --- Get all clients into a table.
 --
--- @param screen An optional screen number.
+-- @param[opt] screen A screen number.
 -- @return A table with all clients.
 -- @function get
 
@@ -147,7 +147,7 @@
 --- Emit a signal.
 --
 -- @param name A signal name.
--- @param ... Various arguments, optional.
+-- @param[opt] ... Various arguments.
 -- @function emit_signal
 
 --- Get the number of instances.
diff --git a/docs/capi/drawable.lua.in b/docs/capi/drawable.lua.in
index 5737522ff..2d322b250 100644
--- a/docs/capi/drawable.lua.in
+++ b/docs/capi/drawable.lua.in
@@ -34,7 +34,7 @@
 --- Emit a signal.
 --
 -- @param name A signal name.
--- @param ... Various arguments, optional.
+-- @param[opt] ... Various arguments.
 -- @function emit_signal
 
 --- Get the number of instances.
diff --git a/docs/capi/drawin.lua.in b/docs/capi/drawin.lua.in
index 0a7d2f662..f100a8d35 100644
--- a/docs/capi/drawin.lua.in
+++ b/docs/capi/drawin.lua.in
@@ -67,7 +67,7 @@
 --- Emit a signal.
 --
 -- @param name A signal name.
--- @param ... Various arguments, optional.
+-- @param[opt] ... Various arguments.
 -- @function emit_signal
 
 --- Get the number of instances.
diff --git a/docs/capi/key.lua.in b/docs/capi/key.lua.in
index f340c9e0c..4575aca51 100644
--- a/docs/capi/key.lua.in
+++ b/docs/capi/key.lua.in
@@ -29,7 +29,7 @@
 --- Emit a signal.
 --
 -- @param name A signal name.
--- @param ... Various arguments, optional.
+-- @param[opt] ... Various arguments.
 -- @function emit_signal
 
 --- Get the number of instances.
diff --git a/docs/capi/screen.lua.in b/docs/capi/screen.lua.in
index 0adac4b29..745d3a6eb 100644
--- a/docs/capi/screen.lua.in
+++ b/docs/capi/screen.lua.in
@@ -36,5 +36,5 @@
 --- Emit a signal to a screen.
 --
 -- @string name A signal name.
--- @param ... Various arguments, optional.
+-- @param[opt] ... Various arguments.
 -- @function emit_signal
diff --git a/docs/capi/tag.lua.in b/docs/capi/tag.lua.in
index 15840ecde..1bf4a7e9b 100644
--- a/docs/capi/tag.lua.in
+++ b/docs/capi/tag.lua.in
@@ -32,7 +32,7 @@
 --- Emit a signal.
 --
 -- @param name A signal name.
--- @param ... Various arguments, optional.
+-- @param[opt] ... Various arguments.
 -- @function emit_signal
 
 --- Get the number of instances.
diff --git a/lib/awful/client.lua.in b/lib/awful/client.lua.in
index 131dc242a..31da2b97e 100644
--- a/lib/awful/client.lua.in
+++ b/lib/awful/client.lua.in
@@ -248,7 +248,7 @@ end
 -- If no client is passed, the focused client will be used.
 --
 -- @tparam int i The index.  Use 1 to get the next, -1 to get the previous.
--- @client[opt] c Optional client.
+-- @client[opt] c The client.
 -- @return A client, or nil if no client is available.
 --
 -- @usage -- focus the next window in the index
@@ -283,7 +283,7 @@ end
 --
 -- @tparam string dir The direction, can be either
 --   `"up"`, `"down"`, `"left"` or `"right"`.
--- @client[opt] c Optional client.
+-- @client[opt] c The client.
 function client.focus.bydirection(dir, c)
     local sel = c or capi.client.focus
     if sel then
@@ -305,7 +305,7 @@ end
 --- Focus a client by the given direction. Moves across screens.
 --
 -- @param dir The direction, can be either "up", "down", "left" or "right".
--- @client[opt] c Optional client.
+-- @client[opt] c The client.
 function client.focus.global_bydirection(dir, c)
     screen = screen or require("awful.screen")
     local sel = c or capi.client.focus
@@ -338,7 +338,7 @@ end
 --- Focus a client by its relative index.
 --
 -- @param i The index.
--- @client[opt] c Optional client.
+-- @client[opt] c The client.
 function client.focus.byidx(i, c)
     local target = client.next(i, c)
     if target then
@@ -348,7 +348,7 @@ end
 
 --- Swap a client with another client in the given direction
 -- @param dir The direction, can be either "up", "down", "left" or "right".
--- @client[opt] c Optional client.
+-- @client[opt] c The client.
 function client.swap.bydirection(dir, c)
     local sel = c or capi.client.focus
     if sel then
@@ -368,7 +368,7 @@ end
 
 --- Swap a client with another client in the given direction. Swaps across screens.
 -- @param dir The direction, can be either "up", "down", "left" or "right".
--- @client[opt] c Optional client.
+-- @client[opt] c The client.
 function client.swap.global_bydirection(dir, c)
     screen = screen or require("awful.screen")
     local sel = c or capi.client.focus
@@ -403,7 +403,7 @@ end
 
 --- Swap a client by its relative index.
 -- @param i The index.
--- @client[opt] c Optional client, otherwise focused one is used.
+-- @client[opt] c The client, otherwise focused one is used.
 function client.swap.byidx(i, c)
     local sel = c or capi.client.focus
     local target = client.next(i, sel)
@@ -415,7 +415,7 @@ end
 --- Cycle clients.
 --
 -- @param clockwise True to cycle clients clockwise.
--- @param[opt] screen Optional screen where to cycle clients.
+-- @param[opt] screen The screen where to cycle clients.
 function client.cycle(clockwise, screen)
     local screen = screen or capi.mouse.screen
     local cls = client.visible(screen)
@@ -436,7 +436,7 @@ end
 
 --- Get the master window.
 --
--- @param[opt] screen Optional screen number, otherwise screen mouse is used.
+-- @param[opt] screen The screen number, otherwise screen mouse is used.
 -- @return The master window.
 function client.getmaster(screen)
     local s = screen or capi.mouse.screen
@@ -467,7 +467,7 @@ end
 -- @param y The relative y coordinate.
 -- @param w The relative width.
 -- @param h The relative height.
--- @client[opt] c The optional client, otherwise focused one is used.
+-- @client[opt] c The client, otherwise focused one is used.
 function client.moveresize(x, y, w, h, c)
     local sel = c or capi.client.focus
     local geometry = sel:geometry()
@@ -480,7 +480,7 @@ end
 
 --- Move a client to a tag.
 -- @param target The tag to move the client to.
--- @client[opt] c Optional client to move, otherwise the focused one is used.
+-- @client[opt] c The client to move, otherwise the focused one is used.
 function client.movetotag(target, c)
     local sel = c or capi.client.focus
     local s = tag.getscreen(target)
@@ -493,7 +493,7 @@ end
 
 --- Toggle a tag on a client.
 -- @param target The tag to toggle.
--- @client[opt] c Optional client to toggle, otherwise the focused one is used.
+-- @client[opt] c The client to toggle, otherwise the focused one is used.
 function client.toggletag(target, c)
     local sel = c or capi.client.focus
     -- Check that tag and client screen are identical
diff --git a/lib/awful/layout/init.lua.in b/lib/awful/layout/init.lua.in
index 1a1369b47..875e851b0 100755
--- a/lib/awful/layout/init.lua.in
+++ b/lib/awful/layout/init.lua.in
@@ -61,7 +61,7 @@ end
 --- Change the layout of the current tag.
 -- @param i Relative index.
 -- @param s The screen number. 
--- @param layouts A table of layouts. (optional)
+-- @param[opt] layouts A table of layouts.
 function layout.inc(i, s, layouts)
     local t = tag.selected(s)
     local layouts = layouts or layout.layouts
diff --git a/lib/awful/menu.lua.in b/lib/awful/menu.lua.in
index 67cd2d3ba..17baa6036 100644
--- a/lib/awful/menu.lua.in
+++ b/lib/awful/menu.lua.in
@@ -366,11 +366,11 @@ function menu:get_root()
 end
 
 --- Add a new menu entry.
--- args.new (Default: awful.menu.entry) The menu entry constructor.
--- args.theme (Optional) The menu entry theme.
 -- args.* params needed for the menu entry constructor.
 -- @param args The item params
--- @param index (Optional) the index where the new entry will inserted
+-- @param args.new (Default: awful.menu.entry) The menu entry constructor.
+-- @param[opt] args.theme The menu entry theme.
+-- @param[opt] index The index where the new entry will inserted.
 function menu:add(args, index)
     if not args then return end
     local theme = load_theme(args.theme or {}, self.theme)
diff --git a/lib/awful/placement.lua.in b/lib/awful/placement.lua.in
index be871b3fa..0aa3c58aa 100644
--- a/lib/awful/placement.lua.in
+++ b/lib/awful/placement.lua.in
@@ -194,7 +194,7 @@ end
 
 --- Place the client centered with respect to a parent or the clients screen.
 -- @param c The client.
--- @param p The parent (optional, nil for screen centering).
+-- @param[opt] p The parent (nil for screen centering).
 -- @return The new client geometry.
 function placement.centered(c, p)
     local c = c or capi.client.focus
@@ -212,7 +212,7 @@ end
 
 --- Place the client centered on the horizontal axis with respect to a parent or the clients screen.
 -- @param c The client.
--- @param p The parent (optional, nil for screen centering).
+-- @param[opt] p The parent (nil for screen centering).
 -- @return The new client geometry.
 function placement.center_horizontal(c, p)
     local c = c or capi.client.focus
@@ -229,7 +229,7 @@ end
 
 --- Place the client centered on the vertical axis with respect to a parent or the clients screen.
 -- @param c The client.
--- @param p The parent (optional, nil for screen centering).
+-- @param[opt] p The parent (nil for screen centering).
 -- @return The new client geometry.
 function placement.center_vertical(c, p)
     local c = c or capi.client.focus
diff --git a/lib/awful/prompt.lua.in b/lib/awful/prompt.lua.in
index 581864792..9ba889b00 100644
--- a/lib/awful/prompt.lua.in
+++ b/lib/awful/prompt.lua.in
@@ -36,8 +36,8 @@ local function itera (inc,a, i)
 end
 
 --- Load history file in history table
--- @param id The data.history identifier which is the path to the filename
--- @param max Optional parameter, the maximum number of entries in file
+-- @param id The data.history identifier which is the path to the filename.
+-- @param[opt] max The maximum number of entries in file.
 local function history_check_load(id, max)
     if id and id ~= ""
         and not data.history[id] then
@@ -188,15 +188,15 @@ end
 -- @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
+-- @param[opt] history_path File path where the history should be
 -- saved, set nil to disable history
--- @param history_max Optional parameter: set the maximum entries in history
+-- @param[opt] history_max Set the maximum entries in history
 -- file, 50 by default
--- @param done_callback Optional parameter: the callback function to always call
+-- @param[opt] done_callback 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
+-- @param[opt] changed_callback The callback function to call
 -- with command as argument when a command was changed.
--- @param keypressed_callback Optional parameter: the callback function to call
+-- @param[opt] keypressed_callback 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
diff --git a/lib/awful/rules.lua.in b/lib/awful/rules.lua.in
index 2811c9a59..a9df3a343 100644
--- a/lib/awful/rules.lua.in
+++ b/lib/awful/rules.lua.in
@@ -180,7 +180,7 @@ end
 --- Apply properties and callbacks to a client.
 -- @client c The client.
 -- @tab props Properties to apply.
--- @tab callbacks Callbacks to apply (optional).
+-- @tab[opt] callbacks Callbacks to apply.
 function rules.execute(c, props, callbacks)
     for property, value in pairs(props) do
         if property ~= "focus" and type(value) == "function" then
diff --git a/lib/awful/screen.lua.in b/lib/awful/screen.lua.in
index 6fd0056c8..1414d39bc 100644
--- a/lib/awful/screen.lua.in
+++ b/lib/awful/screen.lua.in
@@ -30,7 +30,7 @@ data.padding = {}
 -- `screen` table/object.
 -- @param x The x coordinate
 -- @param y The y coordinate
--- @param default Optional default return value. If unspecified, 1 is returned.
+-- @param[opt] default The default return value. If unspecified, 1 is returned.
 function screen.getbycoord(x, y, default)
     for i = 1, capi.screen:count() do
         local geometry = capi.screen[i].geometry
diff --git a/lib/awful/tag.lua.in b/lib/awful/tag.lua.in
index 57f98be03..8e4de5cbd 100644
--- a/lib/awful/tag.lua.in
+++ b/lib/awful/tag.lua.in
@@ -377,7 +377,7 @@ function tag.incmwfact(add, t)
 end
 
 --- Get master width factor.
--- @param t Optional tag.
+-- @param[opt] t The tag.
 function tag.getmwfact(t)
     local t = t or tag.selected()
     return tag.getproperty(t, "mwfact") or 0.5
@@ -385,7 +385,7 @@ end
 
 --- Set the number of master windows.
 -- @param nmaster The number of master windows.
--- @param t Optional tag.
+-- @param[opt] t The tag.
 function tag.setnmaster(nmaster, t)
     local t = t or tag.selected()
     if nmaster >= 0 then
@@ -394,7 +394,7 @@ function tag.setnmaster(nmaster, t)
 end
 
 --- Get the number of master windows.
--- @param t Optional tag.
+-- @param[opt] t The tag.
 function tag.getnmaster(t)
     local t = t or tag.selected()
     return tag.getproperty(t, "nmaster") or 1
@@ -434,7 +434,7 @@ function tag.setncol(ncol, t)
 end
 
 --- Get number of column windows.
--- @param t Optional tag.
+-- @param[opt] t The tag.
 function tag.getncol(t)
     local t = t or tag.selected()
     return tag.getproperty(t, "ncol") or 1
@@ -448,7 +448,7 @@ function tag.incncol(add, t)
 end
 
 --- View no tag.
--- @tparam int screen Optional screen number.
+-- @tparam[opt] int screen The screen number.
 function tag.viewnone(screen)
     local tags = tag.gettags(screen or capi.mouse.screen)
     for i, t in pairs(tags) do
@@ -458,7 +458,7 @@ end
 
 --- View a tag by its taglist index.
 -- @param i The relative index to see.
--- @param screen Optional screen number.
+-- @param[opt] screen The screen number.
 function tag.viewidx(i, screen)
     local screen = screen or capi.mouse.screen
     local tags = tag.gettags(screen)
@@ -523,7 +523,7 @@ end
 
 --- View only a set of tags.
 -- @param tags A table with tags to view only.
--- @param screen Optional screen number of the tags.
+-- @param[opt] screen The screen number of the tags.
 function tag.viewmore(tags, screen)
     local screen = screen or capi.mouse.screen
     local screen_tags = tag.gettags(screen)
diff --git a/lib/awful/titlebar.lua.in b/lib/awful/titlebar.lua.in
index 13db09d8f..40aaecbc9 100644
--- a/lib/awful/titlebar.lua.in
+++ b/lib/awful/titlebar.lua.in
@@ -55,7 +55,7 @@ end
 --- Get a client's titlebar
 -- @class function
 -- @param c The client for which a titlebar is wanted.
--- @param args An optional table with extra arguments for the titlebar. The
+-- @param[opt] args A table with extra arguments for the titlebar. The
 -- "size" is the height of the titlebar. Available "position" values are top,
 -- left, right and bottom. Additionally, the foreground and background colors
 -- can be configured via e.g. "bg_normal" and "bg_focus".
@@ -104,7 +104,7 @@ end
 
 --- Show a client's titlebar.
 -- @param c The client whose titlebar is modified
--- @param position Optional position of the titlebar. Must be one of "left",
+-- @param[opt] position The position of the titlebar. Must be one of "left",
 --        "right", "top", "bottom". Default is "top".
 function titlebar.show(c, position)
     local position = position or "top"
@@ -116,7 +116,7 @@ end
 
 --- Hide a client's titlebar.
 -- @param c The client whose titlebar is modified
--- @param position Optional position of the titlebar. Must be one of "left",
+-- @param[opt] position The position of the titlebar. Must be one of "left",
 --        "right", "top", "bottom". Default is "top".
 function titlebar.hide(c, position)
     local position = position or "top"
@@ -125,7 +125,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 position Optional position of the titlebar. Must be one of "left",
+-- @param[opt] position The position of the titlebar. Must be one of "left",
 --        "right", "top", "bottom". Default is "top".
 function titlebar.toggle(c, position)
     local position = position or "top"
diff --git a/lib/awful/util.lua.in b/lib/awful/util.lua.in
index 5818705e8..a7ff1f1f4 100644
--- a/lib/awful/util.lua.in
+++ b/lib/awful/util.lua.in
@@ -33,7 +33,7 @@ util.shell = os.getenv("SHELL") or "/bin/sh"
 
 local displayed_deprecations = {}
 --- Display a deprecation notice, but only once per traceback.
--- @param see Optional message to a new method / function to use.
+-- @param[opt] see The message to a new method / function to use.
 function util.deprecate(see)
     local tb = debug.traceback()
     if displayed_deprecations[tb] then
@@ -190,7 +190,7 @@ end
 -- @param iconname The name of the icon to search for.
 -- @param exts Table of image extensions allowed, otherwise { 'png', gif' }
 -- @param dirs Table of dirs to search, otherwise { '/usr/share/pixmaps/' }
--- @tparam string size Optional size. If this is specified, subdirectories `x`
+-- @tparam[opt] string size The size. If this is specified, subdirectories `x`
 --   of the dirs are searched first.
 function util.geticonpath(iconname, exts, dirs, size)
     local exts = exts or { 'png', 'gif' }
diff --git a/lib/awful/widget/taglist.lua.in b/lib/awful/widget/taglist.lua.in
index bf30508d7..730afc896 100644
--- a/lib/awful/widget/taglist.lua.in
+++ b/lib/awful/widget/taglist.lua.in
@@ -139,20 +139,20 @@ end
 -- @param filter Filter function to define what clients will be listed.
 -- @param buttons A table with buttons binding to set.
 -- @param style The style overrides default theme.
--- @param update_function Optional function to create a tag widget on each
+-- @param[opt] update_function Function to create a tag widget on each
 --        update. @see awful.widget.common.
--- @param base_widget Optional container widget for tag widgets. Default
+-- @param[opt] base_widget Optional container widget for tag widgets. Default
 --        is wibox.layout.fixed.horizontal().
--- bg_focus The background color for focused client.
--- fg_focus The foreground color for focused client.
--- bg_urgent The background color for urgent clients.
--- fg_urgent The foreground color for urgent clients.
--- squares_sel Optional: a user provided image for selected squares.
--- squares_unsel Optional: a user provided image for unselected squares.
--- squares_sel_empty Optional: a user provided image for selected squares for empty tags.
--- squares_unsel_empty Optional: a user provided image for unselected squares for empty tags.
--- squares_resize Optional: true or false to resize squares.
--- font The font.
+-- @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.
+-- @param base_widget.fg_urgent The foreground color for urgent clients.
+-- @param[opt] base_widget.squares_sel A user provided image for selected squares.
+-- @param[opt] base_widget.squares_unsel A user provided image for unselected squares.
+-- @param[opt] base_widget.squares_sel_empty A user provided image for selected squares for empty tags.
+-- @param[opt] base_widget.squares_unsel_empty A user provided image for unselected squares for empty tags.
+-- @param[opt] base_widget.squares_resize True or false to resize squares.
+-- @param base_widget.font The font.
 function taglist.new(screen, filter, buttons, style, update_function, base_widget)
     local uf = update_function or common.list_update
     local w = base_widget or fixed.horizontal()
diff --git a/lib/awful/widget/tasklist.lua.in b/lib/awful/widget/tasklist.lua.in
index fbf150754..c2cbb4ddf 100644
--- a/lib/awful/widget/tasklist.lua.in
+++ b/lib/awful/widget/tasklist.lua.in
@@ -122,9 +122,9 @@ end
 -- @param filter Filter function to define what clients will be listed.
 -- @param buttons A table with buttons binding to set.
 -- @param style The style overrides default theme.
--- @param update_function Optional function to create a tag widget on each
+-- @param[opt] update_function Function to create a tag widget on each
 --   update. See `awful.widget.common.list_update`.
--- @tparam table base_widget Optional container widget for tag widgets. Default
+-- @tparam[opt] table base_widget Container widget for tag widgets. Default
 --   is `wibox.layout.flex.horizontal`.
 -- @param base_widget.bg_normal The background color for unfocused client.
 -- @param base_widget.bg_normal The background color for unfocused client.
diff --git a/lib/gears/debug.lua.in b/lib/gears/debug.lua.in
index 7c23a1eb3..e1b7478f5 100644
--- a/lib/gears/debug.lua.in
+++ b/lib/gears/debug.lua.in
@@ -17,7 +17,7 @@ local debug = {}
 --- Check that the given condition holds true, else throw an error
 --
 -- @param cond If this is false, throw a lua error with a backtrace.
--- @param[opt] message Message to print in the error (optional).
+-- @param[opt] message Message to print in the error.
 function debug.assert(cond, message)
     local message = message or cond
     if not cond then
diff --git a/lib/naughty/core.lua.in b/lib/naughty/core.lua.in
index 97c6e765b..1ed9743d8 100644
--- a/lib/naughty/core.lua.in
+++ b/lib/naughty/core.lua.in
@@ -173,7 +173,7 @@ end
 -- @param position top_right | top_left | bottom_right | bottom_left
 --             | top_middle | bottom_middle
 -- @param idx Index of the notification
--- @param width Popup width (optional)
+-- @param[opt] width Popup width.
 -- @param height Popup height
 -- @return Absolute position and index in { x = X, y = Y, idx = I } table
 local function get_offset(screen, position, idx, width, height)
diff --git a/lib/wibox/layout/constraint.lua.in b/lib/wibox/layout/constraint.lua.in
index c65e9b5c8..0aeda1ca0 100644
--- a/lib/wibox/layout/constraint.lua.in
+++ b/lib/wibox/layout/constraint.lua.in
@@ -103,11 +103,11 @@ end
 -- that respect the widget's size, eg. fixed layout. In layouts that don't
 -- (fully) respect widget's requested size, the inner widget still might get
 -- drawn with a size that does not fit the constraint, eg. in flex layout.
--- @param widget A widget to use (optional)
--- @param strategy How to constraint the size. 'max' (default), 'min' or
--- 'exact'. (optional)
--- @param width The maximum width of the widget. nil for no limit. (optional)
--- @param height The maximum height of the widget. nil for no limit. (optional)
+-- @param[opt] widget A widget to use.
+-- @param[opt] strategy How to constraint the size. 'max' (default), 'min' or
+-- 'exact'.
+-- @param[opt] width The maximum width of the widget. nil for no limit.
+-- @param[opt] height The maximum height of the widget. nil for no limit.
 local function new(widget, strategy, width, height)
     local ret = widget_base.make_widget()
 
diff --git a/lib/wibox/layout/margin.lua.in b/lib/wibox/layout/margin.lua.in
index f6368a3ee..87a8ff85b 100644
--- a/lib/wibox/layout/margin.lua.in
+++ b/lib/wibox/layout/margin.lua.in
@@ -120,12 +120,12 @@ for k, v in pairs({ "left", "right", "top", "bottom" }) do
 end
 
 --- Returns a new margin layout.
--- @param widget A widget to use (optional)
--- @param left A margin to use on the left side of the widget (optional)
--- @param right A margin to use on the right side of the widget (optional)
--- @param top A margin to use on the top side of the widget (optional)
--- @param bottom A margin to use on the bottom side of the widget (optional)
--- @param color A color for the margins (optional)
+-- @param[opt] widget A widget to use.
+-- @param[opt] left A margin to use on the left side of the widget.
+-- @param[opt] right A margin to use on the right side of the widget.
+-- @param[opt] top A margin to use on the top side of the widget.
+-- @param[opt] bottom A margin to use on the bottom side of the widget.
+-- @param[opt] color A color for the margins.
 local function new(widget, left, right, top, bottom, color)
     local ret = widget_base.make_widget()
 
diff --git a/lib/wibox/layout/mirror.lua.in b/lib/wibox/layout/mirror.lua.in
index 5af772c07..41b17a358 100644
--- a/lib/wibox/layout/mirror.lua.in
+++ b/lib/wibox/layout/mirror.lua.in
@@ -98,8 +98,8 @@ end
 -- :set_widget() to set the widget and
 -- :set_horizontal() and :set_vertical() for the direction.
 -- horizontal and vertical are by default false which doesn't change anything.
--- @param widget The widget to display (optional)
--- @param reflection A table describing the reflection to apply (optional)
+-- @param[opt] widget The widget to display.
+-- @param[opt] reflection A table describing the reflection to apply.
 local function new(widget, reflection)
     local ret = widget_base.make_widget()
     ret.horizontal = false
diff --git a/lib/wibox/layout/rotate.lua.in b/lib/wibox/layout/rotate.lua.in
index c4f5844fc..3a25ef436 100644
--- a/lib/wibox/layout/rotate.lua.in
+++ b/lib/wibox/layout/rotate.lua.in
@@ -99,8 +99,8 @@ end
 --- Returns a new rotate layout. A rotate layout rotates a given widget. Use
 -- :set_widget() to set the widget and :set_direction() for the direction.
 -- The default direction is "north" which doesn't change anything.
--- @param widget The widget to display (optional)
--- @param dir The direction to rotate to (optional)
+-- @param[opt] widget The widget to display.
+-- @param[opt] dir The direction to rotate to.
 local function new(widget, dir)
     local ret = widget_base.make_widget()
 
diff --git a/lib/wibox/widget/background.lua.in b/lib/wibox/widget/background.lua.in
index 591add968..0d85b3dc8 100644
--- a/lib/wibox/widget/background.lua.in
+++ b/lib/wibox/widget/background.lua.in
@@ -96,8 +96,8 @@ end
 
 --- Returns a new background layout. A background layout applies a background
 -- and foreground color to another widget.
--- @param widget The widget to display (optional)
--- @param bg The background to use for that widget (optional)
+-- @param[opt] widget The widget to display.
+-- @param[opt] bg The background to use for that widget.
 local function new(widget, bg)
     local ret = base.make_widget()