Browse Source

doc: Use an explicit tag for all static functions.

This way their name doesn't get mangle by the broken magic. It will also
eventually allow to `error()` in the template when the implicit
`@function` is used.

This commit also fixes a large number of issues found while
proof-reading everything.
Emmanuel Lepage Vallee 5 months ago
parent
commit
b4ece0f053
83 changed files with 586 additions and 102 deletions
  1. 3
    3
      docs/common/cobject.ldoc
  2. 30
    12
      docs/config.ld
  3. 18
    6
      lib/awful/client.lua
  4. 3
    0
      lib/awful/completion.lua
  5. 3
    0
      lib/awful/ewmh.lua
  6. 1
    0
      lib/awful/hotkeys_popup/init.lua
  7. 6
    0
      lib/awful/hotkeys_popup/widget.lua
  8. 4
    0
      lib/awful/key.lua
  9. 5
    5
      lib/awful/keygrabber.lua
  10. 9
    0
      lib/awful/layout/init.lua
  11. 11
    2
      lib/awful/layout/suit/fair.lua
  12. 2
    0
      lib/awful/layout/suit/floating.lua
  13. 1
    0
      lib/awful/layout/suit/tile.lua
  14. 16
    3
      lib/awful/menu.lua
  15. 4
    0
      lib/awful/mouse/init.lua
  16. 13
    0
      lib/awful/placement.lua
  17. 3
    0
      lib/awful/popup.lua
  18. 1
    0
      lib/awful/prompt.lua
  19. 10
    0
      lib/awful/rules.lua
  20. 11
    0
      lib/awful/screen.lua
  21. 9
    0
      lib/awful/spawn.lua
  22. 18
    0
      lib/awful/tag.lua
  23. 13
    0
      lib/awful/titlebar.lua
  24. 2
    1
      lib/awful/tooltip.lua
  25. 4
    0
      lib/awful/util.lua
  26. 2
    3
      lib/awful/wibar.lua
  27. 4
    1
      lib/awful/widget/calendar_popup.lua
  28. 1
    0
      lib/awful/widget/keyboardlayout.lua
  29. 0
    4
      lib/beautiful/gtk.lua
  30. 56
    0
      lib/beautiful/init.lua
  31. 9
    0
      lib/beautiful/theme_assets.lua
  32. 6
    0
      lib/beautiful/xresources.lua
  33. 10
    0
      lib/gears/color.lua
  34. 9
    0
      lib/gears/debug.lua
  35. 17
    0
      lib/gears/filesystem.lua
  36. 8
    0
      lib/gears/geometry.lua
  37. 3
    0
      lib/gears/math.lua
  38. 7
    0
      lib/gears/object.lua
  39. 1
    0
      lib/gears/protected_call.lua
  40. 20
    0
      lib/gears/shape.lua
  41. 6
    0
      lib/gears/sort/topological.lua
  42. 19
    6
      lib/gears/string.lua
  43. 21
    0
      lib/gears/surface.lua
  44. 26
    0
      lib/gears/table.lua
  45. 4
    0
      lib/gears/timer.lua
  46. 7
    0
      lib/gears/wallpaper.lua
  47. 19
    0
      lib/menubar/init.lua
  48. 2
    0
      lib/menubar/menu_gen.lua
  49. 7
    0
      lib/menubar/utils.lua
  50. 5
    0
      lib/naughty/core.lua
  51. 14
    0
      lib/wibox/hierarchy.lua
  52. 27
    1
      lib/wibox/widget/base.lua
  53. 3
    0
      lib/wibox/widget/init.lua
  54. 12
    12
      luaa.c
  55. 1
    1
      mouse.c
  56. 3
    3
      mousegrabber.c
  57. 3
    3
      objects/button.c
  58. 4
    4
      objects/client.c
  59. 4
    4
      objects/drawable.c
  60. 3
    3
      objects/key.c
  61. 5
    5
      objects/screen.c
  62. 5
    5
      objects/tag.c
  63. 10
    10
      root.c
  64. 1
    1
      selection.c
  65. 1
    1
      spawn.c
  66. 1
    0
      tests/examples/awful/placement/bottom.lua
  67. 1
    0
      tests/examples/awful/placement/bottom_left.lua
  68. 1
    0
      tests/examples/awful/placement/bottom_right.lua
  69. 2
    0
      tests/examples/awful/placement/center_horizontal.lua
  70. 1
    0
      tests/examples/awful/placement/center_vertical.lua
  71. 1
    0
      tests/examples/awful/placement/centered.lua
  72. 1
    0
      tests/examples/awful/placement/left.lua
  73. 1
    0
      tests/examples/awful/placement/maximize_horizontally.lua
  74. 1
    0
      tests/examples/awful/placement/maximize_vertically.lua
  75. 1
    0
      tests/examples/awful/placement/right.lua
  76. 1
    0
      tests/examples/awful/placement/stretch_down.lua
  77. 1
    0
      tests/examples/awful/placement/stretch_left.lua
  78. 1
    0
      tests/examples/awful/placement/stretch_right.lua
  79. 1
    0
      tests/examples/awful/placement/stretch_up.lua
  80. 1
    0
      tests/examples/awful/placement/top.lua
  81. 1
    0
      tests/examples/awful/placement/top_left.lua
  82. 1
    0
      tests/examples/awful/placement/top_right.lua
  83. 3
    3
      xkb.c

+ 3
- 3
docs/common/cobject.ldoc View File

@@ -3,7 +3,7 @@
3 3
 /** Disconnect from a signal.
4 4
  * @tparam string name The name of the signal.
5 5
  * @tparam function func The callback that should be disconnected.
6
- * @function disconnect_signal
6
+ * @staticfct disconnect_signal
7 7
  */
8 8
 
9 9
 /** Emit a signal.
@@ -12,13 +12,13 @@
12 12
  * @param ... Extra arguments for the callback functions. Each connected
13 13
  *   function receives the object as first argument and then any extra
14 14
  *   arguments that are given to emit_signal().
15
- * @function emit_signal
15
+ * @staticfct emit_signal
16 16
  */
17 17
 
18 18
 /** Connect to a signal.
19 19
  * @tparam string name The name of the signal.
20 20
  * @tparam function func The callback to call when the signal is emitted.
21
- * @function connect_signal
21
+ * @staticfct connect_signal
22 22
  */
23 23
 
24 24
 /*

+ 30
- 12
docs/config.ld View File

@@ -56,6 +56,9 @@ tparam_alias('screen_or_idx', 'screen|int')
56 56
 new_type("constructorfct", "Constructors", false, "Parameters")
57 57
 -- Hack to get the functions on top of the signals and properties
58 58
 new_type("function", "Functions", false, "Parameters")
59
+-- For "classes", use an explicit type for static functions. This allows
60
+-- @function and its implicit cousin to be banned in the CI.
61
+new_type("staticfct", "Static module functions", false, "Parameters")
59 62
 -- Documentation for objects properties
60 63
 new_type("property", "Object properties", false, "Type")
61 64
 -- Documentation for objects deprecated properties
@@ -141,6 +144,7 @@ file = {
141 144
         '../lib/wibox/container/init.lua',
142 145
         '../lib/naughty/constants.lua',
143 146
         '../lib/naughty/dbus.lua',
147
+        '../lib/beautiful/gtk.lua',
144 148
 
145 149
         -- Ignore some parts of the widget library
146 150
         '../lib/awful/widget/init.lua',
@@ -189,7 +193,23 @@ local coreclassmap = {
189 193
     mouse  = "mouse<span class='listplusign'> and awful.mouse</span>",
190 194
 }
191 195
 
196
+-- Add the full module name in front.
197
+local add_mod = {
198
+    ["function"]   = true,
199
+    constructorfct = true,
200
+    staticfct      = true,
201
+    deprecated     = true,
202
+}
203
+
204
+-- Add the arguments.
205
+local add_args = {
206
+    constructorfct = true,
207
+    staticfct      = true,
208
+}
209
+
192 210
 custom_display_name_handler = function(item, default_handler)
211
+    local ret = default_handler(item)
212
+
193 213
     -- Remove the "namespace" from the signals and properties
194 214
     if no_prefix[item.type] then
195 215
         local name = item.name:match("%.([^.]+)$")
@@ -201,15 +221,22 @@ custom_display_name_handler = function(item, default_handler)
201 221
         return coreclassmap[item.name]
202 222
     end
203 223
 
224
+    -- Undocumented API to make the libraries and classmod "function" section
225
+    -- more consistent. Right now some have their full awful.foo.bar while other
226
+    -- have "just" `bar`. Given we use constructors from metatables, we have no
227
+    -- choice but to use the full function name. It also makes copy/paste easier.
228
+    if add_mod[item.type] and (not ret:find(".", 1, true)) and (not ret:find(":", 1, true)) then
229
+        ret = item.module.name .. "." .. ret
230
+    end
231
+
204 232
     if item.type == "deprecated" or item.type == "deprecatedproperty" then
205
-        return default_handler(item) .. "<i class=\"deprecated_label\"> [deprecated]</i>"
233
+        return ret .. "<i class=\"deprecated_label\"> [deprecated]</i>"
206 234
     end
207 235
 
208 236
     if item.type == "method" then
209 237
         return render_methods(item)
210 238
     end
211 239
 
212
-    local ret = default_handler(item)
213 240
 
214 241
     -- Get rid of the "module:" in front of method names. It is either wrong or
215 242
     -- just redundant.
@@ -221,17 +248,8 @@ custom_display_name_handler = function(item, default_handler)
221 248
         return ret:gsub("^module", item.module.name)
222 249
     end
223 250
 
224
-    -- Undocumented API to make the libraries and classmod "function" section
225
-    -- more consistent. Right now some have their full awful.foo.bar while other
226
-    -- have "just" `bar`. Given we use constructors from metatables, we have no
227
-    -- choice but to use the full function name. It also makes copy/paste easier.
228
-    if (item.type == "function" or item.type == "constructorfct")
229
-      and (not ret:find(".", 1, true)) and (not ret:find(":", 1, true)) then
230
-        ret = item.module.name .. "." .. ret
231
-    end
232
-
233 251
     -- It isn't there by default.
234
-    if item.type == "constructorfct" then
252
+    if add_args[item.type] then
235 253
         ret = ret .. " " .. item.args
236 254
     end
237 255
 

+ 18
- 6
lib/awful/client.lua View File

@@ -239,7 +239,7 @@ end
239 239
 --- Get a client by its relative index to another client.
240 240
 -- If no client is passed, the focused client will be used.
241 241
 --
242
+-- @staticfct awful.client.next
242 243
 -- @tparam int i The index.  Use 1 to get the next, -1 to get the previous.
243 244
 -- @client[opt] sel The client.
244 245
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
@@ -274,7 +274,7 @@ function client.next(i, sel, stacked)
274 274
 end
275 275
 
276 276
 --- Swap a client with another client in the given direction.
277
+-- @staticfct awful.client.swap.bydirection
277 278
 -- @tparam string dir The direction, can be either "up", "down", "left" or "right".
278 279
 -- @client[opt=focused] c The client.
279 280
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
@@ -295,8 +295,9 @@ function client.swap.bydirection(dir, c, stacked)
295 295
     end
296 296
 end
297 297
 
298
---- Swap a client with another client in the given direction. Swaps across screens.
298
+--- Swap a client with another client in the given direction.
299
+-- Swaps across screens.
300
+-- @staticfct awful.client.swap.global_bydirection
299 301
 -- @param dir The direction, can be either "up", "down", "left" or "right".
300 302
 -- @client[opt] sel The client.
301 303
 function client.swap.global_bydirection(dir, sel)
@@ -329,7 +330,7 @@ function client.swap.global_bydirection(dir, sel)
329 330
 end
330 331
 
331 332
 --- Swap a client by its relative index.
333
+-- @staticfct awful.client.swap.byidx
332 334
 -- @param i The index.
333 335
 -- @client[opt] c The client, otherwise focused one is used.
334 336
 function client.swap.byidx(i, c)
@@ -342,7 +343,7 @@ end
342 343
 
343 344
 --- Cycle clients.
344 345
 --
346
+-- @staticfct awful.client.cycle
345 347
 -- @param clockwise True to cycle clients clockwise.
346 348
 -- @param[opt] s The screen where to cycle clients.
347 349
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
@@ -886,7 +887,7 @@ end
886 887
 
887 888
 
888 889
 --- Restore (=unminimize) a random client.
890
+-- @staticfct awful.client.restore
889 891
 -- @param s The screen to use.
890 892
 -- @return The restored client if some client was restored, otherwise nil.
891 893
 function client.restore(s)
@@ -907,7 +908,7 @@ function client.restore(s)
907 908
     return nil
908 909
 end
909 910
 
910
---- Normalize a set of numbers to 1
911
+--- Normalize a set of numbers to 1.
911 912
 -- @param set the set of numbers to normalize
912 913
 -- @param num the number of numbers to normalize
913 914
 local function normalize(set, num)
@@ -1204,7 +1205,7 @@ end
1204 1205
 
1205 1206
 --- Set a client property to be persistent across restarts (via X properties).
1206 1207
 --
1208
+-- @staticfct awful.client.property.persist
1207 1209
 -- @param prop The property name.
1208 1210
 -- @param kind The type (used for register_xproperty).
1209 1211
 --   One of "string", "number" or "boolean".
@@ -1221,16 +1222,17 @@ function client.property.persist(prop, kind)
1221 1222
     end
1222 1223
 end
1223 1224
 
1224
----
1225
+--- Returns an iterator to cycle through clients.
1226
+--
1227
+-- Starting from the client in focus or the given index, all clients that match
1228
+-- a given criteria.
1225 1229
 --
1226 1230
 -- @param filter a function that returns true to indicate a positive match
1227 1231
 -- @param start  what index to start iterating from.  Defaults to using the
1228 1232
 --   index of the currently focused client.
1229 1233
 -- @param s which screen to use.  nil means all screens.
1230 1234
 --
1235
+-- @staticfct awful.client.iterate
1231 1236
 -- @usage -- un-minimize all urxvt instances
1232 1237
 -- local urxvt = function (c)
1233 1238
 --   return awful.rules.match(c, {class = "URxvt"})
@@ -1387,7 +1389,7 @@ do
1387 1389
     -- See `awful.client.focus.history.enable_tracking` to enable it again.
1388 1390
     -- @treturn int The internal value of `disabled_count` (calls to this
1389 1391
     --   function without calling `awful.client.focus.history.enable_tracking`).
1390
-    -- @function awful.client.focus.history.disable_tracking
1392
+    -- @staticfct awful.client.focus.history.disable_tracking
1391 1393
     function client.focus.history.disable_tracking()
1392 1394
         disabled_count = disabled_count + 1
1393 1395
         if disabled_count == 1 then
@@ -1401,7 +1403,7 @@ do
1401 1403
     -- This is the default, but can be disabled
1402 1404
     -- through `awful.client.focus.history.disable_tracking`.
1403 1405
     -- @treturn boolean True if history tracking has been enabled.
1404
-    -- @function awful.client.focus.history.enable_tracking
1406
+    -- @staticfct awful.client.focus.history.enable_tracking
1405 1407
     function client.focus.history.enable_tracking()
1406 1408
         assert(disabled_count > 0)
1407 1409
         disabled_count = disabled_count - 1
@@ -1414,7 +1416,7 @@ do
1414 1416
     --- Is history tracking enabled?
1415 1417
     -- @treturn bool True if history tracking is enabled.
1416 1418
     -- @treturn int The number of times that tracking has been disabled.
1417
-    -- @function awful.client.focus.history.is_enabled
1419
+    -- @staticfct awful.client.focus.history.is_enabled
1418 1420
     function client.focus.history.is_enabled()
1419 1421
         return disabled_count == 0, disabled_count
1420 1422
     end

+ 3
- 0
lib/awful/completion.lua View File

@@ -32,6 +32,7 @@ local bashcomp_src = "@SYSCONFDIR@/bash_completion"
32 32
 --- Enable programmable bash completion in awful.completion.bash at the price of
33 33
 -- a slight overhead.
34 34
 -- @param src The bash completion source file, /etc/bash_completion by default.
35
+-- @staticfct awful.completion.bashcomp_load
35 36
 function completion.bashcomp_load(src)
36 37
     if src then bashcomp_src = src end
37 38
     local c, err = io.popen("/usr/bin/env bash -c 'source " .. bashcomp_src .. "; complete -p'")
@@ -70,6 +71,7 @@ completion.default_shell = nil
70 71
 -- @treturn string The new command.
71 72
 -- @treturn number The new cursor position.
72 73
 -- @treturn table The table with all matches.
74
+-- @staticfct awful.completion.shell
73 75
 function completion.shell(command, cur_pos, ncomp, shell)
74 76
     local wstart = 1
75 77
     local wend = 1
@@ -192,6 +194,7 @@ end
192 194
 -- @param ncomp The number of yet requested completion using current text.
193 195
 -- @param keywords The keywords table uised for completion.
194 196
 -- @return The new match, the new cursor position, the table of all matches.
197
+-- @staticfct awful.completion.generic
195 198
 function completion.generic(text, cur_pos, ncomp, keywords) -- luacheck: no unused args
196 199
     -- The keywords table may be empty
197 200
     if #keywords == 0 then

+ 3
- 0
lib/awful/ewmh.lua View File

@@ -54,6 +54,7 @@ local ewmh = {
54 54
 --- Update a client's settings when its geometry changes, skipping signals
55 55
 -- resulting from calls within.
56 56
 local repair_geometry_lock = false
57
+
57 58
 local function repair_geometry(window)
58 59
     if repair_geometry_lock then return end
59 60
     repair_geometry_lock = true
@@ -166,6 +167,7 @@ end
166 167
 -- @see generic_activate_filters
167 168
 -- @see contextual_activate_filters
168 169
 -- @see remove_activate_filter
170
+-- @staticfct awful.ewmh.add_activate_filter
169 171
 function ewmh.add_activate_filter(f, context)
170 172
     if not context then
171 173
         table.insert(ewmh.generic_activate_filters, f)
@@ -185,6 +187,7 @@ end
185 187
 -- @see generic_activate_filters
186 188
 -- @see contextual_activate_filters
187 189
 -- @see add_activate_filter
190
+-- @staticfct awful.ewmh.remove_activate_filter
188 191
 function ewmh.remove_activate_filter(f, context)
189 192
     local tab = context and (ewmh.contextual_activate_filters[context] or {})
190 193
         or ewmh.generic_activate_filters

+ 1
- 0
lib/awful/hotkeys_popup/init.lua View File

@@ -24,7 +24,7 @@ local hotkeys_popup = {
24 24
 -- @tparam[opt] screen s The screen.
25 25
 -- @tparam[opt=true] boolean show_args.show_awesome_keys Show AwesomeWM hotkeys.
26 26
 -- When set to `false` only app-specific hotkeys will be shown.
27
+-- @staticfct awful.hotkeys_popup.show_help
27 28
 -- @see awful.hotkeys_popup.widget.show_help
28 29
 
29 30
 hotkeys_popup.show_help = hotkeys_popup.widget.show_help

+ 6
- 0
lib/awful/hotkeys_popup/widget.lua View File

@@ -490,6 +490,7 @@ function widget.new(args)
490 490
     -- @tparam[opt] table show_args Additional arguments.
491 491
     -- @tparam[opt=true] boolean show_args.show_awesome_keys Show AwesomeWM hotkeys.
492 492
     -- When set to `false` only app-specific hotkeys will be shown.
493
+    -- @method show_help
493 494
     function widget_instance:show_help(c, s, show_args)
494 495
         show_args = show_args or {}
495 496
         local show_awesome_keys = show_args.show_awesome_keys ~= false
@@ -549,6 +550,7 @@ function widget.new(args)
549 550
     --- Add hotkey descriptions for third-party applications.
550 551
     -- @tparam table hotkeys Table with bindings,
551 552
     -- see `awful.hotkeys_popup.key.vim` as an example.
553
+    -- @method add_hotkeys
552 554
     function widget_instance:add_hotkeys(hotkeys)
553 555
         for group, bindings in pairs(hotkeys) do
554 556
             for _, binding in ipairs(bindings) do
@@ -571,6 +573,7 @@ function widget.new(args)
571 573
     -- @tparam string group hotkeys group name,
572 574
     -- @tparam table data rule data for the group
573 575
     -- see `awful.hotkeys_popup.key.vim` as an example.
576
+    -- @method add_group_rules
574 577
     function widget_instance:add_group_rules(group, data)
575 578
         self.group_rules[group] = data
576 579
     end
@@ -591,6 +594,7 @@ end
591 594
 -- @tparam[opt] table args Additional arguments.
592 595
 -- @tparam[opt=true] boolean args.show_awesome_keys Show AwesomeWM hotkeys.
593 596
 -- When set to `false` only app-specific hotkeys will be shown.
597
+-- @staticfct awful.hotkeys_popup.widget.show_help
594 598
 function widget.show_help(...)
595 599
     return get_default_widget():show_help(...)
596 600
 end
@@ -599,6 +603,7 @@ end
599 603
 -- (default widget instance will be used).
600 604
 -- @tparam table hotkeys Table with bindings,
601 605
 -- see `awful.hotkeys_popup.key.vim` as an example.
606
+-- @staticfct awful.hotkeys_popup.widget.add_hotkeys
602 607
 function widget.add_hotkeys(...)
603 608
     return get_default_widget():add_hotkeys(...)
604 609
 end
@@ -608,6 +613,7 @@ end
608 613
 -- @tparam string group rule group name,
609 614
 -- @tparam table data rule data for the group
610 615
 -- see `awful.hotkeys_popup.key.vim` as an example.
616
+-- @staticfct awful.hotkeys_popup.widget.add_group_rules
611 617
 function widget.add_group_rules(group, data)
612 618
     return get_default_widget():add_group_rules(group, data)
613 619
 end

+ 4
- 0
lib/awful/key.lua View File

@@ -3,7 +3,7 @@
3 3
 --
4 4
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
5 5
 -- @copyright 2009 Julien Danjou
6
+-- @classmod awful.key
6 7
 ---------------------------------------------------------------------------
7 8
 
8 9
 -- Grab environment we need
@@ -59,6 +59,7 @@ capi.awesome.connect_signal("xkb::map_changed"  , function() conversion = nil en
59 59
 -- @tparam table mod A modified table. Valid modifiers are: Any, Mod1,
60 60
 --   Mod2, Mod3, Mod4, Mod5, Shift, Lock and Control.
61 61
 -- @tparam string k The key
62
+-- @staticfct awful.key.execute
62 63
 function key.execute(mod, k)
63 64
     local modmap = generate_conversion_map()
64 65
     local active = capi.awesome._active_modifiers
@@ -111,6 +112,7 @@ end
111 112
 -- @tparam table data User data for key,
112 113
 -- for example {description="select next tag", group="tag"}.
113 114
 -- @treturn table A table with one or several key objects.
115
+-- @constructorfct awful.key
114 116
 function key.new(mod, _key, press, release, data)
115 117
     if type(release)=='table' then
116 118
         data=release
@@ -145,6 +147,7 @@ end
145 147
 -- @param _key The key object.
146 148
 -- @param pressed_mod The modifiers to compare with.
147 149
 -- @param pressed_key The key to compare with.
150
+-- @staticfct awful.key.match
148 151
 function key.match(_key, pressed_mod, pressed_key)
149 152
     -- First, compare key.
150 153
     if pressed_key ~= _key.key then return false end

+ 5
- 5
lib/awful/keygrabber.lua View File

@@ -724,16 +724,6 @@ function keygrab.run_with_keybindings(args)
724 724
     return ret
725 725
 end
726 726
 
727
---- Run a grabbing function.
728
---
729
---
730
---
731
-
732 727
 --- A lower level API to interact with the keygrabber directly.
733 728
 --
734 729
 -- Grab keyboard input and read pressed keys, calling the least callback
@@ -750,7 +740,7 @@ end
750 740
 --
751 741
 -- Here is the content of the modifier table:
752 742
 --
743
+-- <table class='widget_list' border=1>
753 744
 --  <tr style='font-weight: bold;'>
754 745
 --   <th align='center'>Modifier name </th>
755 746
 --   <th align='center'>Key name</th>
@@ -785,7 +775,7 @@ end
785 775
 --     end
786 776
 --   end)
787 777
 -- end
778
+-- @deprecated awful.keygrabber.run
788 779
 function keygrab.run(g)
789 780
     -- Remove the grabber if it is in the stack.
790 781
     keygrab.stop(g)
@@ -807,7 +797,7 @@ end
807 797
 local signals = {}
808 798
 
809 799
 --- Connect to a signal for all keygrabbers at once.
800
+-- @staticfct awful.keygrabber.connect_signal
810 801
 -- @tparam string name The signal name.
811 802
 -- @tparam function callback The callback.
812 803
 function keygrab.connect_signal(name, callback)
@@ -820,7 +810,7 @@ function keygrab.connect_signal(name, callback)
820 810
 end
821 811
 
822 812
 --- Disconnect to a signal for all keygrabbers at once.
813
+-- @staticfct awful.keygrabber.disconnect_signal
823 814
 -- @tparam string name The signal name.
824 815
 -- @tparam function callback The callback.
825 816
 function keygrab.disconnect_signal(name, callback)
@@ -840,7 +830,7 @@ end
840 830
 -- `my_keygrabber:emit_signal(name, ...)`. This function works on the whole
841 831
 -- keygrabber module, not one of its instance.
842 832
 --
833
+-- @staticfct awful.keygrabber.emit_signal
843 834
 -- @tparam string name The signal name.
844 835
 -- @param ... Other arguments for the callbacks.
845 836
 function keygrab.emit_signal(name, ...)

+ 9
- 0
lib/awful/layout/init.lua View File

@@ -73,7 +73,7 @@ layout.layouts = {
73 73
 --    awful.layout.suit.corner.sw,
74 74
 --    awful.layout.suit.corner.se,
75 75
 --
76
+-- @field awful.layout.layouts
76 77
 
77 78
 --- Return the tag layout index (from `awful.layout.layouts`).
78 79
 --
@@ -82,6 +82,7 @@ layout.layouts = {
82 82
 --
83 83
 -- @tparam tag t The tag.
84 84
 -- @treturn nil|number The layout index.
85
+-- @staticfct awful.layout.get_tag_layout_index
85 86
 function layout.get_tag_layout_index(t)
86 87
     return gtable.hasitem(layout.layouts, t.layout)
87 88
 end
@@ -95,6 +96,7 @@ local delayed_arrange = {}
95 96
 --- Get the current layout.
96 97
 -- @param screen The screen.
97 98
 -- @return The layout function.
99
+-- @staticfct awful.layout.get
98 100
 function layout.get(screen)
99 101
     screen = screen or capi.mouse.screen
100 102
     local t = get_screen(screen).selected_tag
@@ -105,6 +107,7 @@ end
105 107
 -- @param i Relative index.
106 108
 -- @param s The screen.
107 109
 -- @param[opt] layouts A table of layouts.
110
+-- @staticfct awful.layout.inc
108 111
 function layout.inc(i, s, layouts)
109 112
     if type(i) == "table" then
110 113
         -- Older versions of this function had arguments (layouts, i, s), but
@@ -150,6 +153,7 @@ end
150 153
 --- Set the layout function of the current tag.
151 154
 -- @param _layout Layout name.
152 155
 -- @tparam[opt=mouse.screen.selected_tag] tag t The tag to modify.
156
+-- @staticfct awful.layout.set
153 157
 function layout.set(_layout, t)
154 158
     t = t or capi.mouse.screen.selected_tag
155 159
     t.layout = _layout
@@ -168,6 +172,7 @@ end
168 172
 -- @treturn table A table with the workarea (x, y, width, height), the screen
169 173
 --   geometry (x, y, width, height), the clients, the screen and sometime, a
170 174
 --   "geometries" table with client as keys and geometry as value
175
+-- @staticfct awful.layout.parameters
171 176
 function layout.parameters(t, screen)
172 177
     screen = get_screen(screen)
173 178
     t = t or screen.selected_tag
@@ -210,6 +215,7 @@ end
210 215
 
211 216
 --- Arrange a screen using its current layout.
212 217
 -- @param screen The screen to arrange.
218
+-- @staticfct awful.layout.arrange
213 219
 function layout.arrange(screen)
214 220
     screen = get_screen(screen)
215 221
     if not screen or delayed_arrange[screen] then return end
@@ -250,6 +256,7 @@ end
250 256
 --- Get the current layout name.
251 257
 -- @param _layout The layout.
252 258
 -- @return The layout name.
259
+-- @staticfct awful.layout.getname
253 260
 function layout.getname(_layout)
254 261
     _layout = _layout or layout.get()
255 262
     return _layout.name
@@ -318,6 +325,7 @@ capi.client.connect_signal("list", function()
318 325
 -- @tparam client c The client
319 326
 -- @tparam string context The context
320 327
 -- @tparam table hints Additional hints
328
+-- @signalhandler awful.layout.move_handler
321 329
 function layout.move_handler(c, context, hints) --luacheck: no unused args
322 330
     -- Quit if it isn't a mouse.move on a tiled layout, that's handled elsewhere
323 331
     if c.floating then return end

+ 11
- 2
lib/awful/layout/suit/fair.lua View File

@@ -88,21 +88,30 @@ local function do_fair(p, orientation)
88 88
     end
89 89
 end
90 90
 
91
---- Horizontal fair layout.
91
+-- Horizontal fair layout.
92 92
 -- @param screen The screen to arrange.
93 93
 fair.horizontal = {}
94 94
 fair.horizontal.name = "fairh"
95
+
95 96
 function fair.horizontal.arrange(p)
96 97
     return do_fair(p, "east")
97 98
 end
98 99
 
99
---- Vertical fair layout.
100
+-- Vertical fair layout.
100 101
 -- @param screen The screen to arrange.
101 102
 fair.name = "fairv"
102 103
 function fair.arrange(p)
103 104
     return do_fair(p, "south")
104 105
 end
105 106
 
107
+--- The fair layout.
108
+-- Try to give all clients the same size.
109
+-- @clientlayout awful.layout.suit.fair
110
+
111
+--- The horizontal fair layout.
112
+-- Try to give all clients the same size.
113
+-- @clientlayout awful.layout.suit.fair.horizontal
114
+
106 115
 return fair
107 116
 
108 117
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

+ 2
- 0
lib/awful/layout/suit/floating.lua View File

@@ -22,6 +22,7 @@ local capi =
22 22
 local floating = {}
23 23
 
24 24
 --- Jump mouse cursor to the client's corner when resizing it.
25
+-- @field awful.layout.suit.floating.resize_jump_to_corner
25 26
 floating.resize_jump_to_corner = true
26 27
 
27 28
 function floating.mouse_resize_handler(c, corner, x, y)
@@ -103,7 +104,7 @@ function floating.arrange()
103 104
 end
104 105
 
105 106
 --- The floating layout.
107
+-- @clientlayout awful.layout.suit.floating
106 108
 
107 109
 floating.name = "floating"
108 110
 

+ 1
- 0
lib/awful/layout/suit/tile.lua View File

@@ -43,6 +43,7 @@ local tile = {}
43 43
 -- @see gears.surface
44 44
 
45 45
 --- Jump mouse cursor to the client's corner when resizing it.
46
+-- @field awful.layout.suit.tile.resize_jump_to_corner
46 47
 tile.resize_jump_to_corner = true
47 48
 
48 49
 local function mouse_resize_handler(c, _, _, _, orientation)

+ 16
- 3
lib/awful/menu.lua View File

@@ -5,7 +5,7 @@
5 5
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
6 6
 -- @author dodo
7 7
 -- @copyright 2008, 2011 Damien Leone, Julien Danjou, dodo
8
+-- @popupmod awful.menu
8 9
 --------------------------------------------------------------------------------
9 10
 
10 11
 local wibox = require("wibox")
@@ -358,6 +358,7 @@ end
358 358
 --- Show a menu.
359 359
 -- @param args The arguments
360 360
 -- @param args.coords Menu position defaulting to mouse.coords()
361
+-- @method show
361 362
 function menu:show(args)
362 363
     args = args or {}
363 364
     local coords = args.coords or nil
@@ -371,6 +372,7 @@ function menu:show(args)
371 372
 end
372 373
 
373 374
 --- Hide a menu popup.
375
+-- @method hide
374 376
 function menu:hide()
375 377
     -- Remove items from screen
376 378
     for i = 1, #self.items do
@@ -389,6 +391,7 @@ end
389 391
 --- Toggle menu visibility.
390 392
 -- @param args The arguments
391 393
 -- @param args.coords Menu position {x,y}
394
+-- @method toggle
392 395
 function menu:toggle(args)
393 396
     if self.wibox.visible then
394 397
         self:hide()
@@ -397,7 +400,8 @@ function menu:toggle(args)
397 400
     end
398 401
 end
399 402
 
400
---- Update menu content
403
+--- Update menu content.
404
+-- @method update
401 405
 function menu:update()
402 406
     if self.wibox.visible then
403 407
         self:show({ coords = { x = self.x, y = self.y } })
@@ -407,6 +411,7 @@ end
407 411
 
408 412
 --- Get the elder parent so for example when you kill
409 413
 -- it, it will destroy the whole family.
414
+-- @method get_root
410 415
 function menu:get_root()
411 416
     return self.parent and menu.get_root(self.parent) or self
412 417
 end
@@ -417,6 +422,7 @@ end
417 422
 -- @param args.new (Default: awful.menu.entry) The menu entry constructor.
418 423
 -- @param[opt] args.theme The menu entry theme.
419 424
 -- @param[opt] index The index where the new entry will inserted.
425
+-- @method add
420 426
 function menu:add(args, index)
421 427
     if not args then return end
422 428
     local theme = load_theme(args.theme or {}, self.theme)
@@ -470,8 +476,9 @@ function menu:add(args, index)
470 476
     return item
471 477
 end
472 478
 
473
---- Delete menu entry at given position
479
+--- Delete menu entry at given position.
480
+-- @param num The position in the table of the menu entry to be deleted; can be also the menu entry itself.
481
+-- @method delete
474 482
 function menu:delete(num)
475 483
     if type(num) == "table" then
476 484
         num = gtable.hasitem(self.items, num)
@@ -511,6 +518,7 @@ end
511 518
 --   returning `true` or `false` to indicate whether the client should be
512 519
 --   included in the menu.
513 520
 -- @return The menu.
521
+-- @constructorfct awful.menu.clients
514 522
 function menu.clients(args, item_args, filter)
515 523
     local cls_t = {}
516 524
     for c in client_iterate(filter or function() return true end) do
@@ -553,6 +561,7 @@ local clients_menu = nil
553 561
 --   returning `true` or `false` to indicate whether the client should be
554 562
 --   included in the menu.
555 563
 -- @return The menu.
564
+-- @constructorfct awful.menu.client_list
556 565
 function menu.client_list(args, item_args, filter)
557 566
     if clients_menu and clients_menu.wibox.visible then
558 567
         clients_menu:hide()
@@ -565,10 +574,11 @@ end
565 574
 
566 575
 --------------------------------------------------------------------------------
567 576
 
568
---- Default awful.menu.entry constructor
577
+--- Default awful.menu.entry constructor.
569 578
 -- @param parent The parent menu (TODO: This is apparently unused)
570 579
 -- @param args the item params
571 580
 -- @return table with 'widget', 'cmd', 'akey' and all the properties the user wants to change
581
+-- @constructorfct awful.menu.entry
572 582
 function menu.entry(parent, args) -- luacheck: no unused args
573 583
     args = args or {}
574 584
     args.text = args[1] or args.text or ""
@@ -668,6 +678,7 @@ end
668 678
 -- * Key auto_expand controls the submenu auto expand behaviour by setting it to true (default) or false.
669 679
 --
670 680
 -- @param parent Specify the parent menu if we want to open a submenu, this value should never be set by the user.
681
+-- @constructorfct awful.menu
671 682
 -- @usage -- The following function builds and shows a menu of clients that match
672 683
 -- -- a particular rule.
673 684
 -- -- Bound to a key, it can be used to select from dozens of terminals open on

+ 4
- 0
lib/awful/mouse/init.lua View File

@@ -72,7 +72,7 @@ function mouse.client_under_pointer()
72 72
 end
73 73
 
74 74
 --- Move a client.
75
+-- @staticfct awful.mouse.client.move
75 76
 -- @param c The client to move, or the focused one if nil.
76 77
 -- @param snap The pixel to snap clients.
77 78
 -- @param finished_cb Deprecated, do not use
@@ -125,7 +125,7 @@ function mouse.client.dragtotag.border(c)
125 125
 end
126 126
 
127 127
 --- Move the wibox under the cursor.
128
+-- @staticfct awful.mouse.wibox.move
128 129
 --@tparam wibox w The wibox to move, or none to use that under the pointer
129 130
 function mouse.wibox.move(w)
130 131
     w = w or mouse.current_wibox
@@ -183,7 +183,7 @@ function mouse.client.corner(c, corner)
183 183
 end
184 184
 
185 185
 --- Resize a client.
186
+-- @staticfct awful.mouse.client.resize
186 187
 -- @param c The client to resize, or the focused one by default.
187 188
 -- @tparam string corner The corner to grab on resize. Auto detected by default.
188 189
 -- @tparam[opt={}] table args A set of `awful.placement` arguments
@@ -417,7 +417,7 @@ end)
417 417
 -- @treturn integer table.y The vertical position
418 418
 -- @treturn table table.buttons Table containing the status of buttons, e.g. field [1] is true
419 419
 --  when button 1 is pressed.
420
+-- @staticfct mouse.coords
420 421
 
421 422
 
422 423
 return mouse

+ 13
- 0
lib/awful/placement.lua View File

@@ -811,7 +811,8 @@ end
811 811
 --   or `wibox`)
812 812
 -- @tparam[opt={}] table args The arguments
813 813
 -- @treturn table The new geometry
814
+-- @treturn string The corner name.
815
+-- @staticfct awful.placement.closest_corner
814 816
 function placement.closest_corner(d, args)
815 817
     args = add_context(args, "closest_corner")
816 818
     d = d or capi.client.focus
@@ -855,6 +856,7 @@ end
855 856
 -- @tparam[opt={}] table args The arguments
856 857
 -- @tparam[opt=client's screen] integer args.screen The screen.
857 858
 -- @treturn table The new client geometry.
859
+-- @staticfct awful.placement.no_offscreen
858 860
 function placement.no_offscreen(c, args)
859 861
 
860 862
     --compatibility with the old API
@@ -897,6 +899,7 @@ end
897 899
 -- @param c The client.
898 900
 -- @tparam[opt={}] table args Other arguments
899 901
 -- @treturn table The new geometry
902
+-- @staticfct awful.placement.no_overlap
900 903
 function placement.no_overlap(c, args)
901 904
     c = c or capi.client.focus
902 905
     args = add_context(args, "no_overlap")
@@ -969,6 +972,7 @@ end
969 972
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`)
970 973
 -- @tparam[opt={}] table args Other arguments
971 974
 -- @treturn table The new geometry
975
+-- @staticfct awful.placement.under_mouse
972 976
 function placement.under_mouse(d, args)
973 977
     args = add_context(args, "under_mouse")
974 978
     d = d or capi.client.focus
@@ -993,6 +997,7 @@ end
993 997
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`)
994 998
 -- @tparam[opt={}] table args Other arguments
995 999
 -- @treturn table The new geometry
1000
+-- @staticfct awful.placement.next_to_mouse
996 1001
 function placement.next_to_mouse(d, args)
997 1002
     if type(args) == "number" then
998 1003
         gdebug.deprecate(
@@ -1042,6 +1047,7 @@ end
1042 1047
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`)
1043 1048
 -- @tparam[opt={}] table args Other arguments
1044 1049
 -- @treturn table The new geometry
1050
+-- @staticfct awful.placement.resize_to_mouse
1045 1051
 function placement.resize_to_mouse(d, args)
1046 1052
     d    = d or capi.client.focus
1047 1053
     args = add_context(args, "resize_to_mouse")
@@ -1119,6 +1125,7 @@ end
1119 1125
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`)
1120 1126
 -- @tparam[opt={}] table args Other arguments
1121 1127
 -- @treturn table The new geometry
1128
+-- @staticfct awful.placement.align
1122 1129
 function placement.align(d, args)
1123 1130
     args = add_context(args, "align")
1124 1131
     d    = d or capi.client.focus
@@ -1193,6 +1200,7 @@ end
1193 1200
 -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`)
1194 1201
 -- @tparam[opt={}] table args The arguments
1195 1202
 -- @treturn table The new geometry
1203
+-- @staticfct awful.placement.stretch
1196 1204
 function placement.stretch(d, args)
1197 1205
     args = add_context(args, "stretch")
1198 1206
 
@@ -1265,6 +1273,7 @@ end
1265 1273
 -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`)
1266 1274
 -- @tparam[opt={}] table args The arguments
1267 1275
 -- @treturn table The new geometry
1276
+-- @staticfct awful.placement.maximize
1268 1277
 function placement.maximize(d, args)
1269 1278
     args = add_context(args, "maximize")
1270 1279
     d    = d or capi.client.focus
@@ -1318,6 +1327,7 @@ end
1318 1327
 -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`)
1319 1328
 -- @tparam[opt={}] table args The arguments
1320 1329
 -- @treturn table The new geometry
1330
+-- @staticfct awful.placement.scale
1321 1331
 function placement.scale(d, args)
1322 1332
     args = add_context(args, "scale_to_percent")
1323 1333
     d    = d or capi.client.focus
@@ -1400,6 +1410,7 @@ end
1400 1410
 -- @treturn table The new geometry
1401 1411
 -- @treturn string The choosen position ("left", "right", "top" or "bottom")
1402 1412
 -- @treturn string The choosen anchor ("front", "middle" or "back")
1413
+-- @staticfct awful.placement.next_to
1403 1414
 function placement.next_to(d, args)
1404 1415
     args = add_context(args, "next_to")
1405 1416
     d    = d or capi.client.focus
@@ -1527,6 +1538,7 @@ end
1527 1538
 -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`)
1528 1539
 -- @tparam[opt={}] table args The arguments
1529 1540
 -- @treturn boolean If the geometry was restored
1541
+-- @staticfct awful.placement.restore
1530 1542
 function placement.restore(d, args)
1531 1543
     if not args or not args.context then return false end
1532 1544
     d = d or capi.client.focus

+ 3
- 0
lib/awful/popup.lua View File

@@ -234,6 +234,7 @@ end
234 234
 -- @see awful.popup.preferred_positions
235 235
 -- @see awful.popup.preferred_anchors
236 236
 -- @treturn table The new geometry
237
+-- @method move_next_to
237 238
 function popup:move_next_to(obj)
238 239
     if self._private.is_relative == false then return end
239 240
 
@@ -256,6 +257,7 @@ end
256 257
 --
257 258
 -- @tparam widget widget The widget
258 259
 -- @tparam[opt=1] number button The button index
260
+-- @method bind_to_widget
259 261
 function popup:bind_to_widget(widget, button)
260 262
     if not self._private.button_for_widget then
261 263
         self._private.button_for_widget = {}
@@ -267,6 +269,7 @@ end
267 269
 
268 270
 --- Unbind the popup from a widget button.
269 271
 -- @tparam widget widget The widget
272
+-- @method unbind_to_widget
270 273
 function popup:unbind_to_widget(widget)
271 274
     widget:disconnect_signal("button::press", self._private.show_fct)
272 275
 end

+ 1
- 0
lib/awful/prompt.lua View File

@@ -454,6 +454,7 @@ end
454 454
 --   with mod table, key and command as arguments when a key was pressed.
455 455
 --   [**DEPRECATED**]
456 456
 -- @see gears.color
457
+-- @staticfct awful.prompt.run
457 458
 function prompt.run(args, textbox, exe_callback, completion_callback,
458 459
                     history_path, history_max, done_callback,
459 460
                     changed_callback, keypressed_callback)

+ 10
- 0
lib/awful/rules.lua View File

@@ -134,6 +134,7 @@ local crules = gmatcher()
134 134
 -- @client c The client.
135 135
 -- @tab rule The rule to check.
136 136
 -- @treturn bool True if it matches, false otherwise.
137
+-- @staticfct awful.rules.match
137 138
 function rules.match(c, rule)
138 139
     return crules:_match(c, rule)
139 140
 end
@@ -142,6 +143,7 @@ end
142 143
 -- @client c The client.
143 144
 -- @tab rule The rule to check.
144 145
 -- @treturn bool True if at least one rule is matched, false otherwise.
146
+-- @staticfct awful.rules.match_any
145 147
 function rules.match_any(c, rule)
146 148
     return crules:_match_any(c, rule)
147 149
 end
@@ -151,6 +153,7 @@ end
151 153
 -- @tab entry Rule entry (with keys `rule`, `rule_any`, `except` and/or
152 154
 --   `except_any`).
153 155
 -- @treturn bool
156
+-- @staticfct awful.rules.matches
154 157
 function rules.matches(c, entry)
155 158
     return crules:matches_rule(c, entry)
156 159
 end
@@ -160,6 +163,7 @@ end
160 163
 -- @tab _rules The rules to check. List with "rule", "rule_any", "except" and
161 164
 --   "except_any" keys.
162 165
 -- @treturn table The list of matched rules.
166
+-- @staticfct awful.rules.matching_rules
163 167
 function rules.matching_rules(c, _rules)
164 168
     return crules:matching_rules(c, _rules)
165 169
 end
@@ -169,13 +173,15 @@ end
169 173
 -- @tab _rules The rules to check. List of tables with `rule`, `rule_any`,
170 174
 --   `except` and `except_any` keys.
171 175
 -- @treturn bool True if at least one rule is matched, false otherwise.
176
+-- @staticfct awful.rules.matches_list
172 177
 function rules.matches_list(c, _rules)
173 178
     return crules:matches_rules(c, _rules)
174 179
 end
175 180
 
176 181
 --- Remove a source.
177 182
 -- @tparam string name The source name.
183
+-- @treturn boolean If the source was removed.
184
+-- @staticfct awful.rules.remove_rule_source
178 185
 function rules.remove_rule_source(name)
179 186
     return crules:remove_matching_source(name)
180 187
 end
@@ -183,6 +189,7 @@ end
183 189
 
184 190
 --- Apply awful.rules.rules to a client.
185 191
 -- @client c The client.
192
+-- @staticfct awful.rules.apply
186 193
 function rules.apply(c)
187 194
     return crules:apply(c)
188 195
 end
@@ -226,7 +233,7 @@ end
226 233
 -- @tparam[opt={}] table precede A list of names of sources this source have a
227 234
 --  priority over.
228 235
 -- @treturn boolean Returns false if a dependency conflict was found.
236
+-- @staticfct awful.rules.add_rule_source
229 237
 
230 238
 function rules.add_rule_source(name, cb, ...)
231 239
     local function callback(_, ...)
@@ -519,7 +526,7 @@ end
519 526
 -- @client c The client.
520 527
 -- @tab props Properties to apply.
521 528
 -- @tab[opt] callbacks Callbacks to apply.
529
+-- @staticfct awful.rules.execute
522 530
 
523 531
 crules._execute = function(_, c, props, callbacks)
524 532
     -- This has to be done first, as it will impact geometry related props.

+ 11
- 0
lib/awful/screen.lua View File

@@ -69,7 +69,7 @@ end
69 69
 --
70 70
 -- The number returned can be used as an index into the global
71 71
 -- `screen` table/object.
72
+-- @staticfct awful.screen.getbycoord
72 73
 -- @tparam number x The x coordinate
73 74
 -- @tparam number y The y coordinate
74 75
 -- @treturn ?number The screen index
@@ -86,7 +86,7 @@ end
86 86
 --
87 87
 -- This moves the mouse pointer to the last known position on the new screen,
88 88
 -- or keeps its position relative to the current focused screen.
89
+-- @staticfct awful.screen.focus
89 90
 -- @screen _screen Screen number (defaults / falls back to mouse.screen).
90 91
 function screen.focus(_screen)
91 92
     client = client or require("awful.client")
@@ -149,7 +149,7 @@ end
149 149
 --
150 150
 -- This moves the mouse pointer to the last known position on the new screen,
151 151
 -- or keeps its position relative to the current focused screen.
152
+-- @staticfct awful.screen.focus_bydirection
152 153
 -- @param dir The direction, can be either "up", "down", "left" or "right".
153 154
 -- @param _screen Screen.
154 155
 function screen.focus_bydirection(dir, _screen)
@@ -166,7 +166,7 @@ end
166 166
 -- This moves the mouse pointer to the last known position on the new screen,
167 167
 -- or keeps its position relative to the current focused screen.
168 168
 --
169
+-- @staticfct awful.screen.focus_relative
169 170
 -- @tparam int offset Value to add to the current focused screen index. 1 to
170 171
 --   focus the next one, -1 to focus the previous one.
171 172
 function screen.focus_relative(offset)
@@ -242,6 +242,7 @@ end
242 242
 -- focused screen by default.
243 243
 -- @tparam client c A client.
244 244
 -- @treturn screen The preferred screen.
245
+-- @staticfct awful.screen.preferred
245 246
 function screen.preferred(c)
246 247
     return capi.awesome.startup and c.screen or screen.focused()
247 248
 end
@@ -254,7 +255,7 @@ end
254 255
 -- It is possible to set `awful.screen.default_focused_args` to override the
255 256
 -- default settings.
256 257
 --
258
+-- @staticfct awful.screen.focused
257 259
 -- @tparam[opt] table args
258 260
 -- @tparam[opt=false] boolean args.client Use the client screen instead of the
259 261
 --   mouse screen.
@@ -272,7 +273,7 @@ end
272 273
 --
273 274
 -- This method computes the different variants of the "usable" screen geometry.
274 275
 --
276
+-- @staticfct screen.get_bounding_geometry
275 277
 -- @tparam[opt={}] table args The arguments
276 278
 -- @tparam[opt=false] boolean args.honor_padding Whether to honor the screen's padding.
277 279
 -- @tparam[opt=false] boolean args.honor_workarea Whether to honor the screen's workarea.
@@ -341,7 +342,7 @@ end
341 342
 --
342 343
 -- This is used by `screen.clients` internally (with `stacked=true`).
343 344
 --
345
+-- @method get_clients
344 346
 -- @tparam[opt=true] boolean stacked Use stacking order? (top to bottom)
345 347
 -- @treturn table The clients list.
346 348
 function screen.object.get_clients(s, stacked)
@@ -430,7 +431,7 @@ end
430 431
 
431 432
 --- Call a function for each existing and created-in-the-future screen.
432 433
 --
434
+-- @staticfct awful.screen.connect_for_each_screen
433 435
 -- @tparam function func The function to call.
434 436
 -- @screen func.screen The screen.
435 437
 function screen.connect_for_each_screen(func)
@@ -441,7 +442,7 @@ function screen.connect_for_each_screen(func)
441 442
 end
442 443
 
443 444
 --- Undo the effect of connect_for_each_screen.
445
+-- @staticfct awful.screen.disconnect_for_each_screen
444 446
 -- @tparam function func The function that should no longer be called.
445 447
 function screen.disconnect_for_each_screen(func)
446 448
     capi.screen.disconnect_signal("added", func)
@@ -525,6 +526,7 @@ end
525 526
 -- defaulting to 96.
526 527
 --
527 528
 -- @tparam boolean enabled Enable or disable automatic DPI support.
529
+-- @staticfct awful.screen.set_auto_dpi_enabled
528 530
 function screen.set_auto_dpi_enabled(enabled)
529 531
     for s in capi.screen do
530 532
         s.data.dpi_cache = nil

+ 9
- 0
lib/awful/spawn.lua View File

@@ -344,6 +344,7 @@ end
344 344
 -- @treturn[1] ?string The startup notification ID, if `sn` is not false, or
345 345
 --   a `callback` is provided.
346 346
 -- @treturn[2] string Error message.
347
+-- @staticfct awful.spawn
347 348
 function spawn.spawn(cmd, sn_rules, callback)
348 349
     if cmd and cmd ~= "" then
349 350
         local enable_sn = (sn_rules ~= false or callback)
@@ -363,6 +364,7 @@ end
363 364
 --- Spawn a program using the shell.
364 365
 -- This calls `cmd` with `$SHELL -c` (via `awful.util.shell`).
365 366
 -- @tparam string cmd The command.
367
+-- @staticfct awful.spawn.with_shell
366 368
 function spawn.with_shell(cmd)
367 369
     if cmd and cmd ~= "" then
368 370
         cmd = { util.shell, "-c", cmd }
@@ -389,6 +391,7 @@ end
389 391
 --   termination.
390 392
 -- @treturn[1] Integer the PID of the forked process.
391 393
 -- @treturn[2] string Error message.
394
+-- @staticfct awful.spawn.with_line_callback
392 395
 function spawn.with_line_callback(cmd, callbacks)
393 396
     local stdout_callback, stderr_callback, done_callback, exit_callback =
394 397
         callbacks.stdout, callbacks.stderr, callbacks.output_done, callbacks.exit
@@ -434,6 +437,7 @@ end
434 437
 -- @treturn[1] Integer the PID of the forked process.
435 438
 -- @treturn[2] string Error message.
436 439
 -- @see spawn.with_line_callback
440
+-- @staticfct awful.spawn.easy_async
437 441
 function spawn.easy_async(cmd, callback)
438 442
     local stdout = ''
439 443
     local stderr = ''
@@ -484,6 +488,7 @@ end
484 488
 -- @treturn[1] Integer the PID of the forked process.
485 489
 -- @treturn[2] string Error message.
486 490
 -- @see spawn.with_line_callback
491
+-- @staticfct awful.spawn.easy_async_with_shell
487 492
 function spawn.easy_async_with_shell(cmd, callback)
488 493
     return spawn.easy_async({ util.shell, "-c", cmd or "" }, callback)
489 494
 end
@@ -495,6 +500,7 @@ end
495 500
 -- @tparam[opt] function done_callback Function that is called when the
496 501
 --   operation finishes (e.g. due to end of file).
497 502
 -- @tparam[opt=false] boolean close Should the stream be closed after end-of-file?
503
+-- @staticfct awful.spawn.read_lines
498 504
 function spawn.read_lines(input_stream, line_callback, done_callback, close)
499 505
     local stream = Gio.DataInputStream.new(input_stream)
500 506
     local function done()
@@ -644,6 +650,7 @@ end
644 650
 --  multiple time.
645 651
 -- @tparam[opt] function callback A callback function when the client is created.
646 652
 -- @see awful.rules
653
+-- @staticfct awful.spawn.once
647 654
 function spawn.once(cmd, rules, matcher, unique_id, callback)
648 655
     local hash = unique_id or hash_command(cmd, rules)
649 656
     local status = register_common(hash, rules, matcher, callback)
@@ -676,6 +683,7 @@ end
676 683
 --  multiple time.
677 684
 -- @tparam[opt] function callback A callback function when the client is created.
678 685
 -- @see awful.rules
686
+-- @staticfct awful.spawn.single_instance
679 687
 function spawn.single_instance(cmd, rules, matcher, unique_id, callback)
680 688
     local hash = unique_id or hash_command(cmd, rules)
681 689
     register_common(hash, rules, matcher, callback)
@@ -703,6 +711,7 @@ local raise_rules = {focus = true, switch_to_tags = true, raise = true}
703 711
 -- @tparam[opt] function callback A callback function when the client is created.
704 712
 -- @see awful.rules
705 713
 -- @treturn client The client if it already exists.
714
+-- @staticfct awful.spawn.raise_or_spawn
706 715
 function spawn.raise_or_spawn(cmd, rules, matcher, unique_id, callback)
707 716
     local hash = unique_id or hash_command(cmd, rules)
708 717
 

+ 18
- 0
lib/awful/tag.lua View File

@@ -296,7 +296,7 @@ function tag.add(name, props)
296 296
 end
297 297
 
298 298
 --- Create a set of tags and attach it to a screen.
299
+-- @staticfct awful.tag.new
299 300
 -- @param names The tag name, in a table
300 301
 -- @param screen The tag screen, or 1 if not set.
301 302
 -- @param layout The layout or layout table to set for this tags by default.
@@ -322,7 +322,7 @@ function tag.new(names, screen, layout)
322 322
 end
323 323
 
324 324
 --- Find a suitable fallback tag.
325
+-- @staticfct awful.tag.find_fallback
325 326
 -- @param screen The screen to look for a tag on. [awful.screen.focused()]
326 327
 -- @param invalids A table of tags we consider unacceptable. [selectedlist(scr)]
327 328
 function tag.find_fallback(screen, invalids)
@@ -340,7 +340,7 @@ end
340 340
 --
341 341
 --    mouse.screen.selected_tag:delete()
342 342
 --
343
+-- @method delete
343 344
 -- @see awful.tag.add
344 345
 -- @see awful.tag.find_fallback
345 346
 -- @tparam[opt=awful.tag.find_fallback()] tag fallback_tag Tag to assign
@@ -429,7 +429,7 @@ function tag.delete(target_tag, fallback_tag)
429 429
 end
430 430
 
431 431
 --- Update the tag history.
432
+-- @staticfct awful.tag.history.update
432 433
 -- @param obj Screen object.
433 434
 function tag.history.update(obj)
434 435
     local s = get_screen(obj)
@@ -470,7 +470,7 @@ function tag.history.update(obj)
470 470
 end
471 471
 
472 472
 --- Revert tag history.
473
+-- @staticfct awful.tag.history.restore
473 474
 -- @param screen The screen.
474 475
 -- @param idx Index in history. Defaults to "previous" which is a special index
475 476
 -- toggling between last two selected sets of tags. Number (eg 1) will go back
@@ -522,6 +522,7 @@ end
522 522
 -- @tparam screen s The screen of the tag
523 523
 -- @tparam string name The name of the tag
524 524
 -- @return The tag found, or `nil`
525
+-- @staticfct awful.tag.find_by_name
525 526
 -- @usage -- For the current screen
526 527
 -- local t = awful.tag.find_by_name(awful.screen.focused(), "name")
527 528
 --
@@ -696,7 +697,7 @@ function tag.setmwfact(mwfact, t)
696 697
 end
697 698
 
698 699
 --- Increase master width factor.
700
+-- @staticfct awful.tag.incmwfact
699 701
 -- @see master_width_factor
700 702
 -- @param add Value to add to master width factor.
701 703
 -- @param t The tag to modify, if null tag.selected() is used.
@@ -972,7 +973,7 @@ function tag.setgap(useless_gap, t)
972 973
 end
973 974
 
974 975
 --- Increase the spacing between clients
976
+-- @staticfct awful.tag.incgap
975 977
 -- @see gap
976 978
 -- @param add Value to add to the spacing between clients
977 979
 -- @param t The tag to modify, if null tag.selected() is used.
@@ -1079,7 +1080,7 @@ end
1079 1080
 
1080 1081
 --- Toggle size fill policy for the master client(s)
1081 1082
 -- between "expand" and "master_width_factor".
1083
+-- @staticfct awful.tag.togglemfpol
1082 1084
 -- @see master_fill_policy
1083 1085
 -- @tparam tag t The tag to modify, if null tag.selected() is used.
1084 1086
 function tag.togglemfpol(t)
@@ -1160,7 +1161,7 @@ function tag.getnmaster(t)
1160 1161
 end
1161 1162
 
1162 1163
 --- Increase the number of master windows.
1164
+-- @staticfct awful.tag.incnmaster
1163 1165
 -- @see master_count
1164 1166
 -- @param add Value to add to number of master windows.
1165 1167
 -- @param[opt] t The tag to modify, if null tag.selected() is used.
@@ -1278,7 +1279,7 @@ function tag.getncol(t)
1278 1279
 end
1279 1280
 
1280 1281
 --- Increase number of column windows.
1282
+-- @staticfct awful.tag.incncol
1281 1283
 -- @param add Value to add to number of column windows.
1282 1284
 -- @param[opt] t The tag to modify, if null tag.selected() is used.
1283 1285
 -- @tparam[opt=false] boolean sensible Limit column_count based on the number
@@ -1309,7 +1310,7 @@ function tag.incncol(add, t, sensible)
1309 1310
 end
1310 1311
 
1311 1312
 --- View no tag.
1313
+-- @staticfct awful.tag.viewnone
1312 1314
 -- @tparam[opt] int|screen screen The screen.
1313 1315
 function tag.viewnone(screen)
1314 1316
     screen = screen or ascreen.focused()
@@ -1322,7 +1323,7 @@ end
1322 1323
 --- View a tag by its taglist index.
1323 1324
 --
1324 1325
 -- This is equivalent to `screen.tags[i]:view_only()`
1326
+-- @staticfct awful.tag.viewidx
1325 1327
 -- @see screen.tags
1326 1328
 -- @param i The **relative** index to see.
1327 1329
 -- @param[opt] screen The screen.
@@ -1357,14 +1358,14 @@ function tag.getidx(query_tag)
1357 1358
 end
1358 1359
 
1359 1360
 --- View next tag. This is the same as tag.viewidx(1).
1361
+-- @staticfct awful.tag.viewnext
1360 1362
 -- @param screen The screen.
1361 1363
 function tag.viewnext(screen)
1362 1364
     return tag.viewidx(1, screen)
1363 1365
 end
1364 1366
 
1365 1367
 --- View previous tag. This is the same a tag.viewidx(-1).
1368
+-- @staticfct awful.tag.viewprev
1366 1369
 -- @param screen The screen.
1367 1370
 function tag.viewprev(screen)
1368 1371
     return tag.viewidx(-1, screen)
@@ -1404,7 +1405,7 @@ end
1404 1405
 -- selected. The tags already selected do not count. To do nothing if one or
1405 1406
 -- more of the tags are already selected, set `maximum` to zero.
1406 1407
 --
1408
+-- @staticfct awful.tag.viewmore
1407 1409
 -- @param tags A table with tags to view only.
1408 1410
 -- @param[opt] screen The screen of the tags.
1409 1411
 -- @tparam[opt=#tags] number maximum The maximum number of tags to select.
@@ -1437,7 +1438,7 @@ function tag.viewmore(tags, screen, maximum)
1437 1438
 end
1438 1439
 
1439 1440
 --- Toggle selection of a tag
1441
+-- @staticfct awful.tag.viewtoggle
1440 1442
 -- @see selected
1441 1443
 -- @tparam tag t Tag to be toggled
1442 1444
 function tag.viewtoggle(t)
@@ -1530,7 +1531,7 @@ end
1530 1531
 --- Add a signal to all attached tags and all tags that will be attached in the
1531 1532
 -- future. When a tag is detached from the screen, its signal is removed.
1532 1533
 --
1534
+-- @staticfct awful.tag.attached_connect_signal
1533 1535
 -- @screen screen The screen concerned, or all if nil.
1534 1536
 -- @tparam[opt] string signal The signal name.
1535 1537
 -- @tparam[opt] function Callback

+ 13
- 0
lib/awful/titlebar.lua View File

@@ -431,8 +431,7 @@ local titlebar = {
431 431
 --- Set a declarative widget hierarchy description.
432 432
 -- See [The declarative layout system](../documentation/03-declarative-layout.md.html)
433 433
 -- @param args An array containing the widgets disposition
434
+-- @method setup
434 435
 
435 436
 
436 437
 local all_titlebars = setmetatable({}, { __mode = 'k' })
@@ -564,6 +563,7 @@ end
564 563
 -- @param c The client whose titlebar is modified
565 564
 -- @param[opt] position The position of the titlebar. Must be one of "left",
566 565
 --   "right", "top", "bottom". Default is "top".
566
+-- @staticfct awful.titlebar.show
567 567
 function titlebar.show(c, position)
568 568
     position = position or "top"
569 569
     if load_titlebars(c, true, position) then return end
@@ -577,6 +577,7 @@ end
577 577
 -- @param c The client whose titlebar is modified
578 578
 -- @param[opt] position The position of the titlebar. Must be one of "left",
579 579
 --   "right", "top", "bottom". Default is "top".
580
+-- @staticfct awful.titlebar.hide
580 581
 function titlebar.hide(c, position)
581 582
     position = position or "top"
582 583
     get_titlebar_function(c, position)(c, 0)
@@ -586,6 +587,7 @@ end
586 587
 -- @param c The client whose titlebar is modified
587 588
 -- @param[opt] position The position of the titlebar. Must be one of "left",
588 589
 --   "right", "top", "bottom". Default is "top".
590
+-- @staticfct awful.titlebar.toggle
589 591
 function titlebar.toggle(c, position)
590 592
     position = position or "top"
591 593
     if load_titlebars(c, true, position) then return end
@@ -602,6 +604,7 @@ end
602 604
 -- This way, you can e.g. modify the font that is used.
603 605
 -- @param c The client for which a titlewidget should be created.
604 606
 -- @return The title widget.
607
+-- @staticfct awful.titlebar.widget.titlewidget
605 608
 function titlebar.widget.titlewidget(c)
606 609
     local ret = textbox()
607 610
     local function update()
@@ -618,6 +621,7 @@ end
618 621
 -- available. This way, you can e.g. disallow resizes.
619 622
 -- @param c The client for which an icon widget should be created.
620 623
 -- @return The icon widget.
624
+-- @staticfct awful.titlebar.widget.iconwidget
621 625
 function titlebar.widget.iconwidget(c)
622 626
     return clienticon(c)
623 627
 end
@@ -635,6 +639,7 @@ end
635 639
 -- @param selector A function that selects the image that should be displayed.
636 640
 -- @param action Function that is called when the button is clicked.
637 641
 -- @return The widget
642
+-- @staticfct awful.titlebar.widget.button
638 643
 function titlebar.widget.button(c, name, selector, action)
639 644
     local ret = imagebox()
640 645
 
@@ -718,6 +723,7 @@ end
718 723
 
719 724
 --- Create a new float button for a client.
720 725
 -- @param c The client for which the button is wanted.
726
+-- @staticfct awful.titlebar.widget.floatingbutton
721 727
 function titlebar.widget.floatingbutton(c)
722 728
     local widget = titlebar.widget.button(c, "floating", aclient.object.get_floating, aclient.floating.toggle)
723 729
     c:connect_signal("property::floating", widget.update)
@@ -726,6 +732,7 @@ end
726 732
 
727 733
 --- Create a new maximize button for a client.
728 734
 -- @param c The client for which the button is wanted.
735
+-- @staticfct awful.titlebar.widget.maximizedbutton
729 736
 function titlebar.widget.maximizedbutton(c)
730 737
     local widget = titlebar.widget.button(c, "maximized", function(cl)
731 738
         return cl.maximized
@@ -738,6 +745,7 @@ end
738 745
 
739 746
 --- Create a new minimize button for a client.
740 747
 -- @param c The client for which the button is wanted.
748
+-- @staticfct awful.titlebar.widget.minimizebutton
741 749
 function titlebar.widget.minimizebutton(c)
742 750
     local widget = titlebar.widget.button(c, "minimize",
743 751
                                           function() return "" end,
@@ -748,12 +756,14 @@ end
748 756
 
749 757
 --- Create a new closing button for a client.
750 758
 -- @param c The client for which the button is wanted.
759
+-- @staticfct awful.titlebar.widget.closebutton
751 760
 function titlebar.widget.closebutton(c)
752 761
     return titlebar.widget.button(c, "close", function() return "" end, function(cl) cl:kill() end)
753 762
 end
754 763
 
755 764
 --- Create a new ontop button for a client.
756 765
 -- @param c The client for which the button is wanted.
766
+-- @staticfct awful.titlebar.widget.ontopbutton
757 767
 function titlebar.widget.ontopbutton(c)
758 768
     local widget = titlebar.widget.button(c, "ontop",
759 769
                                           function(cl) return cl.ontop end,
@@ -764,6 +774,7 @@ end
764 774
 
765 775
 --- Create a new sticky button for a client.
766 776
 -- @param c The client for which the button is wanted.
777
+-- @staticfct awful.titlebar.widget.stickybutton
767 778
 function titlebar.widget.stickybutton(c)
768 779
     local widget = titlebar.widget.button(c, "sticky",
769 780
                                           function(cl) return cl.sticky end,

+ 2
- 1
lib/awful/tooltip.lua View File

@@ -276,20 +276,13 @@ function tooltip:set_align(value)
276 276
 end
277 277
 
278 278
 --- The shape of the tooltip window.
279 279
 --
280 280
 -- @DOC_awful_tooltip_shape_EXAMPLE@
281 281
 --
282 282
 -- @property shape
283 283
 -- @see gears.shape
284 284
 -- @see beautiful.tooltip_shape
285 285
 
286
---- Set the tooltip shape.
287 286
 function tooltip:set_shape(s)
288 287
     self.backgroundbox:set_shape(s)
289 288
 end
@@ -520,7 +513,7 @@ end
520 513
 -- @tparam tooltip self The tooltip.
521 514
 -- @tparam gears.object obj An object with `mouse::enter` and
522 515
 --   `mouse::leave` signals.
516
+-- @method add_to_object
523 517
 function tooltip:add_to_object(obj)
524 518
     if not obj then return end
525 519
 
@@ -533,7 +526,7 @@ end
533 526
 -- @tparam tooltip self The tooltip.
534 527
 -- @tparam gears.object obj An object with `mouse::enter` and
535 528
 --   `mouse::leave` signals.
529
+-- @method remove_from_object
536 530
 function tooltip:remove_from_object(obj)
537 531
     obj:disconnect_signal("mouse::enter", self.show)
538 532
     obj:disconnect_signal("mouse::leave", self.hide)

+ 4
- 0
lib/awful/util.lua View File

@@ -99,6 +99,7 @@ end
99 99
 
100 100
 --- Eval Lua code.
101 101
 -- @return The return value of Lua code.
102
+-- @staticfct awful.util.eval
102 103
 function util.eval(s)
103 104
     return assert(load(s))()
104 105
 end
@@ -129,6 +130,7 @@ end
129 130
 -- @param path The file path.
130 131
 -- @return A function if everything is alright, a string with the error
131 132
 -- otherwise.
133
+-- @staticfct awful.util.checkfile
132 134
 function util.checkfile(path)
133 135
     local f, e = loadfile(path)
134 136
     -- Return function if function, otherwise return error.
@@ -140,6 +142,7 @@ end
140 142
 -- It checks if the configuration file is valid, and then restart if it's ok.
141 143
 -- If it's not ok, the error will be returned.
142 144
 -- @return Never return if awesome restart, or return a string error.
145
+-- @staticfct awful.util.restart
143 146
 function util.restart()
144 147
     local c = util.checkfile(capi.awesome.conffile)
145 148
 
@@ -225,6 +228,7 @@ end
225 228
 -- @param dirs Table of dirs to search, otherwise { '/usr/share/pixmaps/' }
226 229
 -- @tparam[opt] string size The size. If this is specified, subdirectories `x`
227 230
 --   of the dirs are searched first.
231
+-- @staticfct awful.util.geticonpath
228 232
 function util.geticonpath(iconname, exts, dirs, size)
229 233
     exts = exts or { 'png', 'gif' }
230 234
     dirs = dirs or { '/usr/share/pixmaps/', '/usr/share/icons/hicolor/' }

+ 2
- 3
lib/awful/wibar.lua View File

@@ -217,11 +217,6 @@ local function set_position(wb, position, skip_reattach)
217 217
     end
218 218
 end
219 219
 
220
---- Stretch the wibar.
221
---
222
-
223 220
 local function get_stretch(w)
224 221
     return w._stretch
225 222
 end
@@ -233,7 +228,8 @@ local function set_stretch(w, value)
233 228
 end
234 229
 
235 230
 --- Remove a wibar.
231
+-- @method remove
232
+
236 233
 local function remove(self)
237 234
     self.visible = false
238 235
 

+ 4
- 1
lib/awful/widget/calendar_popup.lua View File

@@ -203,6 +203,7 @@ end
203 203
 -- @tparam string position Two-character position of the calendar in the screen
204 204
 -- @tparam screen screen Screen where to display the calendar
205 205
 -- @treturn wibox The wibox calendar
206
+-- @method call_calendar
206 207
 function calendar_popup:call_calendar(offset, position, screen)
207 208
     local inc_offset = offset or 0
208 209
     local pos = position or self.position
@@ -230,7 +231,8 @@ function calendar_popup:call_calendar(offset, position, screen)
230 231
     return self
231 232
 end
232 233
 
233
---- Toggle calendar visibility
234
+--- Toggle calendar visibility.
235
+-- @method toggle
234 236
 function calendar_popup:toggle()
235 237
     self:call_calendar(0)
236 238
     self.visible = not self.visible
@@ -247,6 +249,7 @@ end
247 249
 -- @tparam[opt={}] table args Additional options
248 250
 -- @tparam[opt=true] bool args.on_hover Show popup during mouse hover
249 251
 -- @treturn wibox The wibox calendar
252
+-- @method attach
250 253
 function calendar_popup:attach(widget, position, args)
251 254
     position = position or "tr"
252 255
     args = args or {}

+ 1
- 0
lib/awful/widget/keyboardlayout.lua View File

@@ -135,6 +135,7 @@ end
135 135
 -- xkb_symbols pattern "vendor/file(section):group_idx".
136 136
 -- @tparam string group_names The string awesome.xkb_get_group_names() returns.
137 137
 -- @treturn table An array of tables whose keys are vendor, file, section, and group_idx.
138
+-- @staticfct awful.keyboardlayout.get_groups_from_group_names
138 139
 function keyboardlayout.get_groups_from_group_names(group_names)
139 140
     if group_names == nil then
140 141
         return nil

+ 0
- 4
lib/beautiful/gtk.lua View File

@@ -63,54 +63,6 @@ local function read_gtk_color_properties_from_widget(gtk_widget, properties)
63 63
     return result
64 64
 end
65 65
 
66
-
67
-
68
---- Get GTK+3 theme variables from GtkStyleContext
69
---
70 66
 function gtk.get_theme_variables()
71 67
     if gtk.cached_theme_variables then
72 68
         return gtk.cached_theme_variables

+ 56
- 0
lib/beautiful/init.lua View File

@@ -37,6 +37,56 @@ local descs = setmetatable({}, { __mode = 'k' })
37 37
 local fonts = setmetatable({}, { __mode = 'v' })
38 38
 local active_font
39 39
 
40
+
41
+-- luacheck: max comment line length 300
42
+
43
+--- Get GTK+3 theme variables from GtkStyleContext
44
+-- @treturn table Key-value table with the following structure:
45
+-- <table class='widget_list' border=1>
46
+-- <tr style='font-weight: bold;'> <th align='center'>Result key</th> <th align='center'>StyleContext key</th> <th align='center'>StyleContext fallback #1</th> <th align='center'>StyleContext fallback #2</th> <th align='center'>GTK Widget fallback</th> </tr>
47
+-- <tr> <td>`font_size`</td> <td></td> <td></td> <td></td> <td>Label font-size</td> </tr>
48
+-- <tr> <td>`font_family`</td> <td></td> <td></td> <td></td> <td>Label font-family</td> </tr>
49
+-- <tr> <td>`bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td></td> <td>Window bg</td> </tr>
50
+-- <tr> <td>`fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td></td> <td>Window fg</td> </tr>
51
+-- <tr> <td>`base_color`</td> <td>`theme_base_color`</td> <td></td> <td></td> <td>Entry bg</td> </tr>
52
+-- <tr> <td>`text_color`</td> <td>`theme_text_color`</td> <td></td> <td></td> <td>Entry fg</td> </tr>
53
+-- <tr> <td>`button_bg_color`</td> <td>`theme_button_bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td>Button bg</td> </tr>
54
+-- <tr> <td>`button_fg_color`</td> <td>`theme_button_fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td>Button fg</td> </tr>
55
+-- <tr> <td>`button_border_color`</td> <td></td> <td></td> <td></td> <td>Button border-color</td> </tr>
56
+-- <tr> <td>`button_border_radius`</td> <td></td> <td></td> <td></td> <td>Button border-radius</td> </tr>
57
+-- <tr> <td>`button_border_width`</td> <td></td> <td></td> <td></td> <td>Button border-top-width</td> </tr>
58
+-- <tr> <td>`selected_bg_color`</td> <td>`theme_selected_bg_color`</td> <td></td> <td></td> <td>ToggleButton bg</td> </tr>
59
+-- <tr> <td>`selected_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td></td> <td>ToggleButton fg</td> </tr>
60
+-- <tr> <td>`menubar_bg_color`</td> <td>`menubar_bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td>HeaderBar bg</td> </tr>
61
+-- <tr> <td>`menubar_fg_color`</td> <td>`menubar_fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td>HeaderBar fg</td> </tr>
62
+-- <tr> <td>`header_button_bg_color`</td> <td>`header_button_bg_color`</td> <td>`menubar_bg_color`</td> <td>`theme_bg_color`</td> <td>HeaderBar > Button bg</td> </tr>
63
+-- <tr> <td>`header_button_fg_color`</td> <td>`header_button_fg_color`</td> <td>`menubar_fg_color`</td> <td>`theme_fg_color`</td> <td>HeaderBar > Button fg</td> </tr>
64
+-- <tr> <td>`header_button_border_color`</td> <td></td> <td></td> <td></td> <td>HeaderBar > Button border-color</td> </tr>
65
+-- <tr> <td>`error_color`</td> <td>`error_color`</td> <td>`error_bg_color`</td> <td></td> <td>destructive Button bg</td> </tr>
66
+-- <tr> <td>`error_bg_color`</td> <td>`error_bg_color`</td> <td>`error_color`</td> <td></td> <td>destructive Button bg</td> </tr>
67
+-- <tr> <td>`error_fg_color`</td> <td>`error_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td>destructive Button fg</td> </tr>
68
+-- <tr> <td>`warning_color`</td> <td>`warning_color`</td> <td>`warning_bg_color`</td> <td></td> <td></td> </tr>
69
+-- <tr> <td>`warning_bg_color`</td> <td>`warning_bg_color`</td> <td>`warning_color`</td> <td></td> <td></td> </tr>
70
+-- <tr> <td>`warning_fg_color`</td> <td>`warning_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td></td> </tr>
71
+-- <tr> <td>`success_color`</td> <td>`success_color`</td> <td>`success_bg_color`</td> <td></td> <td></td> </tr>
72
+-- <tr> <td>`success_bg_color`</td> <td>`success_bg_color`</td> <td>`success_color`</td> <td></td> <td></td> </tr>
73
+-- <tr> <td>`success_fg_color`</td> <td>`success_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td></td> </tr>
74
+-- <tr> <td>`tooltip_bg_color`</td> <td>`theme_tooltip_bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td></td> </tr>
75
+-- <tr> <td>`tooltip_fg_color`</td> <td>`theme_tooltip_fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td></td> </tr>
76
+-- <tr> <td>`osd_bg_color`</td> <td>`osd_bg`</td> <td>`theme_tooltip_bg_color`</td> <td>`theme_bg_color`</td> <td></td> </tr>
77
+-- <tr> <td>`osd_fg_color`</td> <td>`osd_fg`</td> <td>`theme_tooltip_fg_color`</td> <td>`theme_fg_color`</td> <td></td> </tr>
78
+-- <tr> <td>`osd_border_color`</td> <td>`osd_borders_color`</td> <td>`osd_fg_color`</td> <td></td> <td></td> </tr>
79
+-- <tr> <td>`wm_bg_color`</td> <td>`wm_bg`</td> <td>`menubar_bg_color`</td> <td>`theme_bg_color`</td> <td>HeaderBar bg</td> </tr>
80
+-- <tr> <td>`wm_border_focused_color`</td> <td>`wm_border_focused`</td> <td>`theme_selected_bg_color`</td> <td></td> <td>ToggleButton bg</td> </tr>
81
+-- <tr> <td>`wm_border_unfocused_color`</td> <td>`wm_border_unfocused`</td> <td>`wm_border`</td> <td>`menubar_bg_color`</td> <!--<td>`theme_bg_color`</td>--> <td>HeaderBar bg</td> </tr>
82
+-- <tr> <td>`wm_title_focused_color`</td> <td>`wm_title_focused`</td> <td>`wm_title`</td> <td>`theme_selected_fg_color`</td> <td>ToggleButton fg</td> </tr>
83
+-- <tr> <td>`wm_title_unfocused_color`</td> <td>`wm_title_unfocused`</td> <td>`wm_unfocused_title`</td> <td>`menubar_fg_color`</td> <!--<td>`theme_fg_color`</td>--> <td>HeaderBar fg</td> </tr>
84
+-- <tr> <td>`wm_icons_focused_color`</td> <td>`wm_icons_focused`</td> <td>`wm_title_focused`</td> <td>`theme_selected_fg_color`</td> <td>ToggleButton fg</td> </tr>
85
+-- <tr> <td>`wm_icons_unfocused_color`</td> <td>`wm_icons_unfocused`</td> <td>`wm_title_unfocused`</td> <td>`menubar_fg_color`</td> <!--<td>`theme_fg_color`</td>--> <td>HeaderBar fg</td> </tr>
86
+-- </table>
87
+--
88
+-- @staticfct beautiful.gtk.get_theme_variables
89
+
40 90
 --- The default font.
41 91
 -- @beautiful beautiful.font
42 92
 
@@ -155,6 +205,7 @@ end
155 205
 -- See https://developer.gnome.org/pango/stable/pango-Fonts.html#PangoFontDescription.
156 206
 -- @tparam string|lgi.Pango.FontDescription name The name of the font.
157 207
 -- @treturn lgi.Pango.FontDescription
208
+-- @staticfct beautiful.get_font
158 209
 function beautiful.get_font(name)
159 210
     return load_font(name).description
160 211
 end
@@ -165,6 +216,7 @@ end
165 216
 -- @tparam string|Pango.FontDescription name The base font.
166 217
 -- @tparam string merge Attributes that should be merged, e.g. "bold".
167 218
 -- @treturn lgi.Pango.FontDescription
219
+-- @staticfct beautiful.get_merged_font
168 220
 function beautiful.get_merged_font(name, merge)
169 221
     local font = beautiful.get_font(name)
170 222
     merge = Pango.FontDescription.from_string(merge)
@@ -175,7 +227,8 @@ end
175 227
 
176 228
 --- Get the height of a font.
177 229
 --
230
+-- @param name Name of the font.
231
+-- @staticfct beautiful.get_font_height
178 232
 function beautiful.get_font_height(name)
179 233
     return load_font(name).height
180 234
 end
@@ -208,6 +261,7 @@ end
208 261
 --   the theme file (which should return a table) or directly a table
209 262
 --   containing all the theme values.
210 263
 -- @treturn true|nil True if successful, nil in case of error.
264
+-- @staticfct beautiful.init
211 265
 function beautiful.init(config)
212 266
     if config then
213 267
         local state, t_theme = nil, nil
@@ -258,6 +312,7 @@ end
258 312
 --- Get the current theme.
259 313
 --
260 314
 -- @treturn table The current theme table.
315
+-- @staticfct beautiful.get
261 316
 function beautiful.get()
262 317
     return theme
263 318
 end

+ 9
- 0
lib/beautiful/theme_assets.lua View File

@@ -3,7 +3,7 @@
3 3
 --
4 4
 -- @author Yauhen Kirylau &lt;yawghen@gmail.com&gt;
5 5
 -- @copyright 2015 Yauhen Kirylau
6
+-- @module beautiful
6 7
 ----------------------------------------------------------------------------
7 8
 
8 9
 local cairo = require("lgi").cairo
@@ -19,6 +19,7 @@ local theme_assets = {}
19 19
 -- @tparam number size Size.
20 20
 -- @tparam color fg Background color.
21 21
 -- @return Image with the square.
22
+-- @staticfct beautiful.theme_assets.taglist_squares_sel
22 23
 function theme_assets.taglist_squares_sel(size, fg)
23 24
     local img = cairo.ImageSurface(cairo.Format.ARGB32, size, size)
24 25
     local cr = cairo.Context(img)
@@ -31,6 +32,7 @@ end
31 32
 -- @tparam number size Size.
32 33
 -- @tparam color fg Background color.
33 34
 -- @return Image with the square.
35
+-- @staticfct beautiful.theme_assets.taglist_squares_unsel
34 36
 function theme_assets.taglist_squares_unsel(size, fg)
35 37
     local img = cairo.ImageSurface(cairo.Format.ARGB32, size, size)
36 38
     local cr = cairo.Context(img)
@@ -84,6 +86,7 @@ end
84 86
 -- @tparam color bg Background color.
85 87
 -- @tparam color fg Main foreground color.
86 88
 -- @tparam color alt_fg Accent foreground color.
89
+-- @staticfct beautiful.theme_assets.gen_awesome_name
87 90
 function theme_assets.gen_awesome_name(cr, height, bg, fg, alt_fg)
88 91
     local ls = height/10 -- letter_size
89 92
     local letter_line = ls/18
@@ -152,6 +155,7 @@ end
152 155
 -- @tparam number height Height.
153 156
 -- @tparam color bg Background color.
154 157
 -- @tparam color fg Foreground color.
158
+-- @staticfct beautiful.theme_assets.gen_logo
155 159
 function theme_assets.gen_logo(cr, width, height, bg, fg)
156 160
     local ls = math.min(width, height)
157 161
 
@@ -174,6 +178,7 @@ end
174 178
 -- @tparam color bg Background color.
175 179
 -- @tparam color fg Background color.
176 180
 -- @return Image with the logo.
181
+-- @staticfct beautiful.theme_assets.awesome_icon
177 182
 function theme_assets.awesome_icon(size, bg, fg)
178 183
     local img = cairo.ImageSurface(cairo.Format.ARGB32, size, size)
179 184
     local cr = cairo.Context(img)
@@ -187,6 +192,7 @@ end
187 192
 -- @tparam color alt_fg Accent foreground color.
188 193
 -- @tparam screen s Screen (to get wallpaper size).
189 194
 -- @return Wallpaper image.
195
+-- @staticfct beautiful.theme_assets.wallpaper
190 196
 function theme_assets.wallpaper(bg, fg, alt_fg, s)
191 197
     s = s or screen.primary
192 198
     local height = s.geometry.height
@@ -215,6 +221,7 @@ end
215 221
 -- @tparam string postfix `nil`, `"hover"` or `"press"`.
216 222
 -- @tparam string toggle_state `nil`, `"active"` or `"inactive"`.
217 223
 -- @treturn table Beautiful theme table with the images recolored.
224
+-- @staticfct beautiful.theme_assets.recolor_titlebar
218 225
 function theme_assets.recolor_titlebar(theme, color, state, postfix, toggle_state)
219 226
     if postfix then postfix='_'..postfix end
220 227
     if toggle_state then toggle_state='_'..toggle_state end
@@ -266,6 +273,7 @@ end
266 273
 -- @tparam table theme Beautiful theme table
267 274
 -- @tparam color color Icons' color.
268 275
 -- @treturn table Beautiful theme table with the images recolored.
276
+-- @staticfct beautiful.theme_assets.recolor_layout
269 277
 function theme_assets.recolor_layout(theme, color)
270 278
     for _, layout_name in ipairs({
271 279
         'layout_fairh',

+ 6
- 0
lib/beautiful/xresources.lua View File

@@ -3,7 +3,7 @@
3 3
 --
4 4
 -- @author Yauhen Kirylau &lt;yawghen@gmail.com&gt;
5 5
 -- @copyright 2015 Yauhen Kirylau
6
+-- @module beautiful
6 7
 ----------------------------------------------------------------------------
7 8
 
8 9
 -- Grab environment
@@ -45,7 +45,8 @@ local fallback = {
45 45
 }
46 46
 
47 47
 --- Get current base colorscheme from xrdb.
48
+-- @treturn table Color table with keys 'background', 'foreground' and 'color0'..'color15'.
49
+-- @staticfct beautiful.xresources.get_current_theme
48 50
 function xresources.get_current_theme()
49 51
     local keys = { 'background', 'foreground' }
50 52
     for i=0,15 do table.insert(keys, "color"..i) end
@@ -77,7 +78,7 @@ end
77 78
 -- This function is deprecated. Use `s.dpi` and avoid getting the DPI without
78 79
 -- a screen.
79 80
 --
81
+-- @deprecated beautiful.xresources.get_dpi
80 82
 -- @tparam[opt] integer|screen s The screen.
81 83
 -- @treturn number DPI value.
82 84
 
@@ -118,6 +119,7 @@ end
118 119
 --- Set DPI for a given screen (defaults to global).
119 120
 -- @tparam number dpi DPI value.
120 121
 -- @tparam[opt] integer s Screen.
122
+-- @staticfct beautiful.xresources.set_dpi
121 123
 function xresources.set_dpi(dpi, s)
122 124
     s = get_screen(s)
123 125
     if not s then
@@ -132,6 +134,7 @@ end
132 134
 -- @tparam number size Size
133 135
 -- @tparam[opt] integer|screen s The screen.
134 136
 -- @treturn integer Resulting size (rounded to integer).
137
+-- @staticfct beautiful.xresources.apply_dpi
135 138
 function xresources.apply_dpi(size, s)
136 139
     return round(size / 96 * xresources.get_dpi(s))
137 140
 end

+ 10
- 0
lib/gears/color.lua View File

@@ -32,10 +32,6 @@
32 32
 -- calling :set_matrix() on it, because this function uses a cache and your
33 33
 -- changes could thus have unintended side effects. Use @{create_pattern_uncached}
34 34
 -- if you need to modify the returned pattern.
35 35
 --
36 36
 -- @author Uli Schlachter
37 37
 -- @copyright 2010 Uli Schlachter
@@ -65,6 +61,7 @@ local pattern_cache
65 61
 -- @param col The color to parse
66 62
 -- @treturn table 4 values representing color in RGBA format (each of them in
67 63
 -- [0, 1] range) or nil if input is incorrect.
64
+-- @staticfct gears.color.parse_color
68 65
 -- @usage -- This will return 0, 1, 0, 1
69 66
 -- gears.color.parse_color("#00ff00ff")
70 67
 function color.parse_color(col)
@@ -123,6 +120,7 @@ end
123 120
 --
124 121
 -- @param col The color for the pattern
125 122
 -- @return A cairo pattern object
123
+-- @staticfct gears.color.create_solid_pattern
126 124
 function color.create_solid_pattern(col)
127 125
     if col == nil then
128 126
         col = "#000000"
@@ -136,6 +134,7 @@ end
136 134
 --
137 135
 -- @param file The filename of the file
138 136
 -- @return a cairo pattern object
137
+-- @staticfct gears.color.create_png_pattern
139 138
 function color.create_png_pattern(file)
140 139
     if type(file) == "table" then
141 140
         file = file.file
@@ -192,6 +191,7 @@ end
192 191
 -- For the explanation of `<stops>`, see `color.create_pattern`.
193 192
 -- @tparam string|table arg The argument describing the pattern.
194 193
 -- @return a cairo pattern object
194
+-- @staticfct gears.color.create_linear_pattern
195 195
 function color.create_linear_pattern(arg)
196 196
     local pat
197 197
 
@@ -217,6 +217,7 @@ end
217 217
 -- For the explanation of `<stops>`, see `color.create_pattern`.
218 218
 -- @tparam string|table arg The argument describing the pattern
219 219
 -- @return a cairo pattern object
220
+-- @staticfct gears.color.create_radial_pattern
220 221
 function color.create_radial_pattern(arg)
221 222
     local pat
222 223
 
@@ -249,6 +250,7 @@ color.types = {
249 250
 -- @see create_pattern
250 251
 -- @param col The string describing the pattern.
251 252
 -- @return a cairo pattern object
253
+-- @staticfct gears.color.create_pattern_uncached
252 254
 function color.create_pattern_uncached(col)
253 255
     -- If it already is a cairo pattern, just leave it as that
254 256
     if cairo.Pattern:is_type_of(col) then
@@ -273,6 +275,7 @@ end
273 275
 
274 276
 --- Create a pattern from a given string, same as @{gears.color}.
275 277
 -- @see gears.color
278
+-- @staticfct gears.color.create_pattern
276 279
 function color.create_pattern(col)
277 280
     if cairo.Pattern:is_type_of(col) then
278 281
         return col
@@ -285,6 +288,7 @@ end
285 288
 -- operator OVER) doesn't influence the visual result.
286 289
 -- @param col An argument that `create_pattern` accepts.
287 290
 -- @return The pattern if it is surely opaque, else nil
291
+-- @staticfct gears.color.create_opaque_pattern
288 292
 function color.create_opaque_pattern(col)
289 293
     local pattern = color.create_pattern(col)
290 294
     local kind = pattern:get_type()
@@ -335,6 +339,7 @@ end
335 339
 -- @param image Image or path to it.
336 340
 -- @param new_color New color.
337 341
 -- @return Recolored image.
342
+-- @staticfct gears.color.recolor_image
338 343
 function color.recolor_image(image, new_color)
339 344
     if type(image) == 'string' then
340 345
         image = surface.duplicate_surface(image)
@@ -349,6 +354,7 @@ end
349 354
 -- @param check_color The color to check.
350 355
 -- @tparam string fallback The color to return if the first is invalid. (default: black)
351 356
 -- @treturn string color if it is valid, else fallback.
357
+-- @staticfct gears.color.ensure_pango_color
352 358
 function color.ensure_pango_color(check_color, fallback)
353 359
     check_color = tostring(check_color)
354 360
     -- Pango markup supports alpha, PangoColor does not. Thus, check for this.

+ 9
- 0
lib/gears/debug.lua View File

@@ -49,6 +49,7 @@ end
49 49
 -- @param tag The name of the value.
50 50
 -- @tparam[opt] int depth Depth of recursion.
51 51
 -- @return string A string that contains the expanded value of data.
52
+-- @staticfct gears.debug.dump_return
52 53
 function debug.dump_return(data, tag, depth)
53 54
     return dump_raw(data, nil, tag, depth)
54 55
 end
@@ -57,23 +58,27 @@ end
57 58
 -- @param data Table to print.
58 59
 -- @param tag The name of the table.
59 60
 -- @tparam[opt] int depth Depth of recursion.
61
+-- @staticfct gears.debug.dump
60 62
 function debug.dump(data, tag, depth)
61 63
     print(debug.dump_return(data, tag, depth))
62 64
 end
63 65
 
64 66
 --- Print an warning message
67
+-- @tparam string message The warning message to print.
68
+-- @staticfct gears.debug.print_warning
65 69
 function debug.print_warning(message)
66 70
     io.stderr:write(os.date("%Y-%m-%d %T W: awesome: ") .. tostring(message) .. "\n")
67 71
 end
68 72
 
69 73
 --- Print an error message
74
+-- @tparam string message The error message to print.
75
+-- @staticfct gears.debug.print_error
70 76
 function debug.print_error(message)
71 77
     io.stderr:write(os.date("%Y-%m-%d %T E: awesome: ") .. tostring(message) .. "\n")
72 78
 end
73 79
 
74 80
 local displayed_deprecations = {}
81
+
75 82
 --- Display a deprecation notice, but only once per traceback.
76 83
 --
77 84
 -- This function also emits the `debug::deprecate` signal on the `awesome`
@@ -84,6 +89,7 @@ local displayed_deprecations = {}
84 89
 -- @tparam boolean args.raw Print the message as-is without the automatic context
85 90
 -- @tparam integer args.deprecated_in Print the message only when Awesome's
86 91
 --   version is equal to or greater than deprecated_in.
92
+-- @staticfct gears.debug.deprecate
87 93
 function debug.deprecate(see, args)
88 94
     args = args or {}
89 95
     if args.deprecated_in then
@@ -124,6 +130,7 @@ end
124 130
 -- @tparam string old_name The old class name
125 131
 -- @tparam string new_name The new class name
126 132
 -- @treturn table A proxy class.
133
+-- @staticfct gears.debug.deprecate_class
127 134
 function debug.deprecate_class(fallback, old_name, new_name)
128 135
     local message = old_name.." has been renamed to "..new_name
129 136
 

+ 17
- 0
lib/gears/filesystem.lua View File

@@ -26,6 +26,7 @@ end
26 26
 --- Create a directory, including all missing parent directories.
27 27
 -- @tparam string dir The directory.
28 28
 -- @return (true, nil) on success, (false, err) on failure
29
+-- @staticfct gears.filesystem.make_directories
29 30
 function filesystem.make_directories(dir)
30 31
     return make_directory(Gio.File.new_for_path(dir))
31 32
 end
@@ -37,7 +38,8 @@ end
37 38
 
38 39
 --- Create all parent directories for a given path.
39 40
 -- @tparam string path The path whose parents should be created.
41
+-- @return (true, nil) on success, (false, err) on failure.
42
+-- @staticfct gears.filesystem.make_parent_directories
40 43
 function filesystem.make_parent_directories(path)
41 44
     return make_directory(Gio.File.new_for_path(path):get_parent())
42 45
 end
@@ -45,6 +47,7 @@ end
45 47
 --- Check if a file exists, is readable and not a directory.
46 48
 -- @tparam string filename The file path.
47 49
 -- @treturn boolean True if file exists and is readable.
50
+-- @staticfct gears.filesystem.file_readable
48 51
 function filesystem.file_readable(filename)
49 52
     local gfile = Gio.File.new_for_path(filename)
50 53
     local gfileinfo = gfile:query_info("standard::type,access::can-read",
@@ -56,6 +59,7 @@ end
56 59
 --- Check if a file exists, is executable and not a directory.
57 60
 -- @tparam string filename The file path.
58 61
 -- @treturn boolean True if file exists and is executable.
62
+-- @staticfct gears.filesystem.file_executable
59 63
 function filesystem.file_executable(filename)
60 64
     local gfile = Gio.File.new_for_path(filename)
61 65
     local gfileinfo = gfile:query_info("standard::type,access::can-execute",
@@ -67,6 +71,7 @@ end
67 71
 --- Check if a path exists, is readable and a directory.
68 72
 -- @tparam string path The directory path.
69 73
 -- @treturn boolean True if path exists and is readable.
74
+-- @staticfct gears.filesystem.dir_readable
70 75
 function filesystem.dir_readable(path)
71 76
     local gfile = Gio.File.new_for_path(path)
72 77
     local gfileinfo = gfile:query_info("standard::type,access::can-read",
@@ -78,30 +83,35 @@ end
78 83
 --- Check if a path is a directory.
79 84
 -- @tparam string path The directory path
80 85
 -- @treturn boolean True if path exists and is a directory.
86
+-- @staticfct gears.filesystem.is_dir
81 87
 function filesystem.is_dir(path)
82 88
     return Gio.File.new_for_path(path):query_file_type({}) == "DIRECTORY"
83 89
 end
84 90
 
85 91
 --- Get the config home according to the XDG basedir specification.
86 92
 -- @return the config home (XDG_CONFIG_HOME) with a slash at the end.
93
+-- @staticfct gears.filesystem.get_xdg_config_home
87 94
 function filesystem.get_xdg_config_home()
88 95
     return (os.getenv("XDG_CONFIG_HOME") or os.getenv("HOME") .. "/.config") .. "/"
89 96
 end
90 97
 
91 98
 --- Get the cache home according to the XDG basedir specification.
92 99
 -- @return the cache home (XDG_CACHE_HOME) with a slash at the end.
100
+-- @staticfct gears.filesystem.get_xdg_cache_home
93 101
 function filesystem.get_xdg_cache_home()
94 102
     return (os.getenv("XDG_CACHE_HOME") or os.getenv("HOME") .. "/.cache") .. "/"
95 103
 end
96 104
 
97 105
 --- Get the data home according to the XDG basedir specification.
98 106
 -- @treturn string the data home (XDG_DATA_HOME) with a slash at the end.
107
+-- @staticfct gears.filesystem.get_xdg_data_home
99 108
 function filesystem.get_xdg_data_home()
100 109
     return (os.getenv("XDG_DATA_HOME") or os.getenv("HOME") .. "/.local/share") .. "/"
101 110
 end
102 111
 
103 112
 --- Get the data dirs according to the XDG basedir specification.
104 113
 -- @treturn table the data dirs (XDG_DATA_DIRS) with a slash at the end of each entry.
114
+-- @staticfct gears.filesystem.get_xdg_data_dirs
105 115
 function filesystem.get_xdg_data_dirs()
106 116
     local xdg_data_dirs = os.getenv("XDG_DATA_DIRS") or "/usr/share:/usr/local/share"
107 117
     return gtable.map(
@@ -112,12 +122,14 @@ end
112 122
 --- Get the path to the user's config dir.
113 123
 -- This is the directory containing the configuration file ("rc.lua").
114 124
 -- @return A string with the requested path with a slash at the end.
125
+-- @staticfct gears.filesystem.get_configuration_dir
115 126
 function filesystem.get_configuration_dir()
116 127
     return awesome.conffile:match(".*/") or "./"
117 128
 end
118 129
 
119 130
 --- Get the path to a directory that should be used for caching data.
120 131
 -- @return A string with the requested path with a slash at the end.
132
+-- @staticfct gears.filesystem.get_cache_dir
121 133
 function filesystem.get_cache_dir()
122 134
     local result = filesystem.get_xdg_cache_home() .. "awesome/"
123 135
     filesystem.make_directories(result)
@@ -126,12 +138,14 @@ end
126 138
 
127 139
 --- Get the path to the directory where themes are installed.
128 140
 -- @return A string with the requested path with a slash at the end.
141
+-- @staticfct gears.filesystem.get_themes_dir
129 142
 function filesystem.get_themes_dir()
130 143
     return (os.getenv('AWESOME_THEMES_PATH') or awesome.themes_path) .. "/"
131 144
 end
132 145
 
133 146
 --- Get the path to the directory where our icons are installed.
134 147
 -- @return A string with the requested path with a slash at the end.
148
+-- @staticfct gears.filesystem.get_awesome_icon_dir
135 149
 function filesystem.get_awesome_icon_dir()
136 150
     return (os.getenv('AWESOME_ICON_PATH') or awesome.icon_path) .. "/"
137 151
 end
@@ -141,6 +155,7 @@ end
141 155
 -- default paths.
142 156
 -- @param d The directory to get (either "config" or "cache").
143 157
 -- @return A string containing the requested path.
158
+-- @staticfct gears.filesystem.get_dir
144 159
 function filesystem.get_dir(d)
145 160
     if d == "config" then
146 161
         -- No idea why this is what is returned, I recommend everyone to use
@@ -159,6 +174,7 @@ end
159 174
 --   If ommited, all files are considered.
160 175
 -- @treturn string|nil A randomly selected filename from the specified path (with
161 176
 --   a specified extension if required) or nil if no suitable file is found.
177
+-- @staticfct gears.filesystem.get_random_file_from_dir
162 178
 function filesystem.get_random_file_from_dir(path, exts)
163 179
     local files, valid_exts = {}, {}
164 180
 

+ 8
- 0
lib/gears/geometry.lua View File

@@ -21,7 +21,8 @@ local gears = {geometry = {rectangle = {} } }
21 21
 -- @tparam number geom.height The rectangle height
22 22
 -- @tparam number x X coordinate of point
23 23
 -- @tparam number y Y coordinate of point
24
+-- @treturn number The squared distance of the rectangle to the provided point.
25
+-- @staticfct gears.geometry.rectangle.get_square_distance
24 26
 function gears.geometry.rectangle.get_square_distance(geom, x, y)
25 27
     local dist_x, dist_y = 0, 0
26 28
     if x < geom.x then
@@ -42,6 +43,7 @@ end
42 43
 -- @tparam number x The x coordinate
43 44
 -- @tparam number y The y coordinate
44 45
 -- @return The key from the closest geometry.
46
+-- @staticfct gears.geometry.rectangle.get_closest_by_coord
45 47
 function gears.geometry.rectangle.get_closest_by_coord(list, x, y)
46 48
     local dist = math.huge
47 49
     local ret = nil
@@ -66,6 +68,7 @@ end
66 68
 -- @tparam number y The y coordinate
67 69
 -- @return The key from the closest geometry. In case no result is found, *nil*
68 70
 --  is returned.
71
+-- @staticfct gears.geometry.rectangle.get_by_coord
69 72
 function gears.geometry.rectangle.get_by_coord(list, x, y)
70 73
     for k, geometry in pairs(list) do
71 74
         if x >= geometry.x and x < geometry.x + geometry.width
@@ -126,6 +129,7 @@ end
126 129
 -- @tparam table recttbl A table of rectangle specifications.
127 130
 -- @tparam table cur The current rectangle.
128 131
 -- @return The index for the rectangle in recttbl closer to cur in the given direction. nil if none found.
132
+-- @staticfct gears.geometry.rectangle.get_in_direction
129 133
 function gears.geometry.rectangle.get_in_direction(dir, recttbl, cur)
130 134
     local dist, dist_min
131 135
     local target = nil
@@ -151,6 +155,7 @@ end
151 155
 -- @param a The area.
152 156
 -- @param b The other area.
153 157
 -- @return True if they intersect, false otherwise.
158
+-- @staticfct gears.geometry.rectangle.area_intersect_area
154 159
 function gears.geometry.rectangle.area_intersect_area(a, b)
155 160
     return (b.x < a.x + a.width
156 161
             and b.x + b.width > a.x
@@ -170,6 +175,7 @@ end
170 175
 -- @tparam number b.width The rectangle width
171 176
 -- @tparam number b.height The rectangle height
172 177
 -- @treturn table The intersect area.
178
+-- @staticfct gears.geometry.rectangle.get_intersection
173 179
 function gears.geometry.rectangle.get_intersection(a, b)
174 180
     local g = {}
175 181
     g.x = math.max(a.x, b.x)
@@ -191,6 +197,7 @@ end
191 197
 -- @tparam number elem.width The rectangle width
192 198
 -- @tparam number elem.height The rectangle height
193 199
 -- @return The new area list.
200
+-- @staticfct gears.geometry.rectangle.area_remove
194 201
 function gears.geometry.rectangle.area_remove(areas, elem)
195 202
     for i = #areas, 1, -1 do
196 203
         -- Check if the 'elem' intersect

+ 3
- 0
lib/gears/math.lua View File

@@ -37,10 +37,9 @@ end
37 37
 -- For example, if we consider a set with value { 10, 15, 34 },
38 38
 -- it will return a table containing 2^n set:
39 39
 -- { }, { 10 }, { 15 }, { 34 }, { 10, 15 }, { 10, 34 }, etc.
40 40
 -- @param set A set.
41 41
 -- @return A table with all subset.
42
+-- @staticfct gears.math.subsets
42 43
 function gmath.subsets(set)
43 44
     local mask = {}
44 45
     local ret = {}
@@ -56,11 +55,10 @@ function gmath.subsets(set)
56 55
 end
57 56
 
58 57
 --- Make i cycle.
59 58
 -- @param t A length. Must be greater than zero.
60 59
 -- @param i An absolute index to fit into #t.
61 60
 -- @return An integer in (1, t) or nil if t is less than or equal to zero.
61
+-- @staticfct gears.math.cycle
62 62
 function gmath.cycle(t, i)
63 63
     if t < 1 then return end
64 64
     i = i % t
@@ -71,10 +69,9 @@ function gmath.cycle(t, i)
71 69
 end
72 70
 
73 71
 --- Round a number to an integer.
74 72
 -- @tparam number x
75 73
 -- @treturn integer
74
+-- @staticfct gears.math.round
76 75
 function gmath.round(x)
77 76
     return math.floor(x + 0.5)
78 77
 end

+ 7
- 0
lib/gears/object.lua View File

@@ -49,6 +49,7 @@ end
49 49
 --@DOC_text_gears_object_signal_EXAMPLE@
50 50
 -- @tparam string name The name of the signal
51 51
 -- @tparam function func The callback to call when the signal is emitted
52
+-- @method connect_signal
52 53
 function object:connect_signal(name, func)
53 54
     assert(type(func) == "function", "callback must be a function, got: " .. type(func))
54 55
     local sig = find_signal(self, name)
@@ -95,6 +96,7 @@ end
95 96
 -- collected and automatically disconnects the signal when that happens.
96 97
 -- @tparam string name The name of the signal
97 98
 -- @tparam function func The callback to call when the signal is emitted
99
+-- @method weak_connect_signal
98 100
 function object:weak_connect_signal(name, func)
99 101
     assert(type(func) == "function", "callback must be a function, got: " .. type(func))
100 102
     local sig = find_signal(self, name)
@@ -105,6 +107,7 @@ end
105 107
 --- Disonnect to a signal.
106 108
 -- @tparam string name The name of the signal
107 109
 -- @tparam function func The callback that should be disconnected
110
+-- @method disconnect_signal
108 111
 function object:disconnect_signal(name, func)
109 112
     local sig = find_signal(self, name)
110 113
     sig.weak[func] = nil
@@ -117,6 +120,7 @@ end
117 120
 -- @param ... Extra arguments for the callback functions. Each connected
118 121
 --   function receives the object as first argument and then any extra arguments
119 122
 --   that are given to emit_signal()
123
+-- @method emit_signal
120 124
 function object:emit_signal(name, ...)
121 125
     local sig = find_signal(self, name)
122 126
     for func in pairs(sig.strong) do
@@ -179,7 +183,8 @@ end
179 183
 --   when an unknown property is set.
180 184
 -- @tparam[opt=nil] table args.class
181 185
 -- @treturn table A new object
186
+-- @constructorfct gears.object
187
+
182 188
 local function new(args)
183 189
     args = args or {}
184 190
     local ret = {}
@@ -236,6 +241,7 @@ end
236 241
 -- @tparam[opt=2] integer level Level for `debug.getinfo(level, "S")`.
237 242
 --   Typically 2 or 3.
238 243
 -- @treturn string The module name, e.g. "wibox.container.background".
244
+-- @staticfct gears.object.modulename
239 245
 function object.modulename(level)
240 246
     return debug.getinfo(level, "S").source:gsub(".*/lib/", ""):gsub("/", "."):gsub("%.lua", "")
241 247
 end

+ 1
- 0
lib/gears/protected_call.lua View File

@@ -43,6 +43,7 @@ end
43 43
 -- @tparam function func The function to call
44 44
 -- @param ... Arguments to the function
45 45
 -- @return The result of the given function, or nothing if an error occurred.
46
+-- @staticfct gears.protected_call
46 47
 function protected_call.call(func, ...)
47 48
     return do_pcall(func, ...)
48 49
 end

+ 20
- 0
lib/gears/shape.lua View File

@@ -55,6 +55,7 @@ local module = {}
55 55
 -- @tparam number width The rectangle width
56 56
 -- @tparam number height The rectangle height
57 57
 -- @tparam number radius the corner radius
58
+-- @staticfct gears.shape.rounded_rect
58 59
 function module.rounded_rect(cr, width, height, radius)
59 60
 
60 61
     radius = radius or 10
@@ -83,7 +84,8 @@ end
83 84
 --
84 85
 -- @param cr A cairo content
85 86
 -- @param width The rectangle width
87
+-- @param height The rectangle height.
88
+-- @staticfct gears.shape.rounded_bar
86 89
 function module.rounded_bar(cr, width, height)
87 90
     module.rounded_rect(cr, width, height, height / 2)
88 91
 end
@@ -100,6 +102,7 @@ end
100 102
 -- @tparam boolean br If the bottom right corner is rounded
101 103
 -- @tparam boolean bl If the bottom left corner is rounded
102 104
 -- @tparam number rad The corner radius
105
+-- @staticfct gears.shape.partially_rounded_rect
103 106
 function module.partially_rounded_rect(cr, width, height, tl, tr, br, bl, rad)
104 107
     rad = rad or 10
105 108
     if width / 2 < rad then
@@ -151,6 +154,7 @@ end
151 154
 -- @tparam[opt=5] number corner_radius The corner radius
152 155
 -- @tparam[opt=10] number arrow_size The width and height of the arrow
153 156
 -- @tparam[opt=width/2 - arrow_size/2] number arrow_position The position of the arrow
157
+-- @staticfct gears.shape.infobubble
154 158
 function module.infobubble(cr, width, height, corner_radius, arrow_size, arrow_position)
155 159
     arrow_size     = arrow_size     or 10
156 160
     corner_radius  = math.min((height-arrow_size)/2, corner_radius or 5)
@@ -184,6 +188,7 @@ end
184 188
 -- @tparam number width The shape width
185 189
 -- @tparam number height The shape height
186 190
 -- @tparam[opt=height/2] number arrow_length The length of the arrow part
191
+-- @staticfct gears.shape.rectangular_tag
187 192
 function module.rectangular_tag(cr, width, height, arrow_length)
188 193
     arrow_length = arrow_length or height/2
189 194
     if arrow_length > 0 then
@@ -213,6 +218,7 @@ end
213 218
 -- @tparam[opt=head_width] number head_width The width of the head (/\) of the arrow
214 219
 -- @tparam[opt=width /2] number shaft_width The width of the shaft of the arrow
215 220
 -- @tparam[opt=height/2] number shaft_length The head_length of the shaft (the rest is the head)
221
+-- @staticfct gears.shape.arrow
216 222
 function module.arrow(cr, width, height, head_width, shaft_width, shaft_length)
217 223
     shaft_length = shaft_length or height / 2
218 224
     shaft_width  = shaft_width  or width  / 2
@@ -237,6 +243,7 @@ end
237 243
 -- @param cr A cairo context
238 244
 -- @tparam number width The shape width
239 245
 -- @tparam number height The shape height
246
+-- @staticfct gears.shape.hexagon
240 247
 function module.hexagon(cr, width, height)
241 248
     cr:move_to(height/2,0)
242 249
     cr:line_to(width-height/2,0)
@@ -256,6 +263,7 @@ end
256 263
 -- @tparam number width The shape width
257 264
 -- @tparam number height The shape height
258 265
 -- @tparam[opt=height/2] number arrow_depth The width of the arrow part of the shape
266
+-- @staticfct gears.shape.powerline
259 267
 function module.powerline(cr, width, height, arrow_depth)
260 268
     arrow_depth = arrow_depth or height/2
261 269
     local offset = 0
@@ -283,6 +291,7 @@ end
283 291
 -- @param cr A cairo context
284 292
 -- @tparam number width The shape width
285 293
 -- @tparam number height The shape height
294
+-- @staticfct gears.shape.isosceles_triangle
286 295
 function module.isosceles_triangle(cr, width, height)
287 296
     cr:move_to( width/2, 0      )
288 297
     cr:line_to( width  , height )
@@ -298,6 +307,7 @@ end
298 307
 -- @tparam number width The shape width
299 308
 -- @tparam number height The shape height
300 309
 -- @tparam[opt=width/3] number thickness The cross section thickness
310
+-- @staticfct gears.shape.cross
301 311
 function module.cross(cr, width, height, thickness)
302 312
     thickness = thickness or width/3
303 313
     local xpadding   = (width  - thickness) / 2
@@ -325,6 +335,7 @@ end
325 335
 -- @tparam number width The shape width
326 336
 -- @tparam number height The shape height
327 337
 -- @tparam number corner_radius
338
+-- @staticfct gears.shape.octogon
328 339
 function module.octogon(cr, width, height, corner_radius)
329 340
     corner_radius = corner_radius or math.min(10, math.min(width, height)/4)
330 341
     local offset = math.sqrt( (corner_radius*corner_radius) / 2 )
@@ -348,6 +359,7 @@ end
348 359
 -- @tparam number width The shape width
349 360
 -- @tparam number height The shape height
350 361
 -- @tparam[opt=math.min(width  height) / 2)] number radius The radius
362
+-- @staticfct gears.shape.circle
351 363
 function module.circle(cr, width, height, radius)
352 364
     radius = radius or math.min(width, height) / 2
353 365
     cr:move_to(width/2+radius, height/2)
@@ -362,6 +374,7 @@ end
362 374
 -- @param cr A cairo context
363 375
 -- @tparam number width The shape width
364 376
 -- @tparam number height The shape height
377
+-- @staticfct gears.shape.rectangle
365 378
 function module.rectangle(cr, width, height)
366 379
     cr:rectangle(0, 0, width, height)
367 380
 end
@@ -375,6 +388,7 @@ end
375 388
 -- @tparam number width The shape width
376 389
 -- @tparam number height The shape height
377 390
 -- @tparam[opt=width/3] number base_width The parallelogram base width
391
+-- @staticfct gears.shape.parallelogram
378 392
 function module.parallelogram(cr, width, height, base_width)
379 393
     base_width = base_width or width/3
380 394
     cr:move_to(width-base_width, 0      )
@@ -391,6 +405,7 @@ end
391 405
 -- @param cr A cairo context
392 406
 -- @tparam number width The shape width
393 407
 -- @tparam number height The shape height
408
+-- @staticfct gears.shape.losange
394 409
 function module.losange(cr, width, height)
395 410
     cr:move_to(width/2 , 0        )
396 411
     cr:line_to(width   , height/2 )
@@ -411,6 +426,7 @@ end
411 426
 -- @tparam[opt=0] number start_angle The start angle (in radian)
412 427
 -- @tparam[opt=math.pi/2] number end_angle The end angle (in radian)
413 428
 -- @tparam[opt=math.min(width height)/2] number radius The shape height
429
+-- @staticfct gears.shape.pie
414 430
 function module.pie(cr, width, height, start_angle, end_angle, radius)
415 431
     radius = radius or math.floor(math.min(width, height)/2)
416 432
     start_angle, end_angle = start_angle or 0, end_angle or math.pi/2
@@ -444,6 +460,7 @@ end
444 460
 -- @tparam[opt=math.pi/2] number end_angle The end angle (in radian)
445 461
 -- @tparam[opt=false] boolean start_rounded if the arc start rounded
446 462
 -- @tparam[opt=false] boolean end_rounded if the arc end rounded
463
+-- @staticfct gears.shape.arc
447 464
 function module.arc(cr, width, height, thickness, start_angle, end_angle, start_rounded, end_rounded)
448 465
     start_angle = start_angle or 0
449 466
     end_angle   = end_angle   or math.pi/2
@@ -562,6 +579,7 @@ end
562 579
 -- @tparam number h The shape height
563 580
 -- @tparam number percent The progressbar percent
564 581
 -- @tparam boolean hide_left Do not draw the left side of the shape
582
+-- @staticfct gears.shape.radial_progress
565 583
 function module.radial_progress(cr, w, h, percent, hide_left)
566 584
     percent = percent or 1
567 585
     local total_length = (2*(w-h))+2*((h/2)*math.pi)
@@ -628,6 +646,7 @@ end
628 646
 --
629 647
 -- @param shape A shape function
630 648
 -- @return A transformation handle, also act as a shape function
649
+-- @staticfct gears.shape.transform
631 650
 function module.transform(shape)
632 651
 
633 652
     -- Apply the transformation matrix and apply the shape, then restore

+ 6
- 0
lib/gears/sort/topological.lua View File

@@ -18,6 +18,7 @@ end
18 18
 --- Ensure that `node` appears after all `dependencies`.
19 19
 -- @param node The node that edges are added to.
20 20
 -- @tparam table dependencies List of nodes that have to appear before `node`.
21
+-- @method append
21 22
 function tsort:append(node, dependencies)
22 23
     add_node(self, node)
23 24
     for _, dep in ipairs(dependencies) do
@@ -29,6 +30,7 @@ end
29 30
 --- Ensure that `node` appears before all `subordinates`.
30 31
 -- @param node The node that edges are added to.
31 32
 -- @tparam table subordinates List of nodes that have to appear after `node`.
33
+-- @method prepend
32 34
 function tsort:prepend(node, subordinates)
33 35
     for _, dep in ipairs(subordinates) do
34 36
         self:append(dep, { node })
@@ -63,6 +65,7 @@ end
63 65
 --- Create a copy of this topological sort.
64 66
 -- This is useful to backup it before adding elements that can potentially
65 67
 -- have circular dependencies and thus render the original useless.
68
+-- @method clone
66 69
 function tsort:clone()
67 70
     local new = tsort.topological()
68 71
 
@@ -75,6 +78,7 @@ end
75 78
 --- Remove a node from the topological map.
76 79
 --
77 80
 -- @param node The node
81
+-- @method remove
78 82
 function tsort:remove(node)
79 83
     self._edges[node] = nil
80 84
     for _, deps in pairs(self._edges) do
@@ -86,6 +90,7 @@ end
86 90
 -- @treturn[1] table A sorted list of nodes
87 91
 -- @treturn[2] nil
88 92
 -- @return[2] A node around which a loop exists
93
+-- @method sort
89 94
 function tsort:sort()
90 95
     local result, state = {}, {}
91 96
     for node in pairs(self._edges) do
@@ -104,7 +109,7 @@ end
104 109
 --
105 110
 --@DOC_text_gears_sort_topological_EXAMPLE@
106 111
 --
112
+-- @constructorfct gears.sort.topological
107 113
 
108 114
 function tsort.topological()
109 115
     return setmetatable({

+ 19
- 6
lib/gears/string.lua View File

@@ -7,43 +7,41 @@
7 7
 local gstring = {}
8 8
 
9 9
 local xml_entity_names = { ["'"] = "&apos;", ["\""] = "&quot;", ["<"] = "&lt;", [">"] = "&gt;", ["&"] = "&amp;" };
10
+
10 11
 --- Escape a string from XML char.
11 12
 -- Useful to set raw text in textbox.
12 13
 -- @param text Text to escape.
13 14
 -- @return Escape text.
15
+-- @staticfct gears.string.xml_escape
14 16
 function gstring.xml_escape(text)
15 17
     return text and text:gsub("['&<>\"]", xml_entity_names) or nil
16 18
 end
17 19
 
18 20
 local xml_entity_chars = { lt = "<", gt = ">", nbsp = " ", quot = "\"", apos = "'", ndash = "-", mdash = "-",
19
-						   amp = "&" };
21
+                           amp = "&" };
22
+
20 23
 --- Unescape a string from entities.
21 24
 -- @param text Text to unescape.
22 25
 -- @return Unescaped text.
26
+-- @staticfct gears.string.xml_unescape
23 27
 function gstring.xml_unescape(text)
24 28
     return text and text:gsub("&(%a+);", xml_entity_chars) or nil
25 29
 end
26 30
 
27 31
 --- Count number of lines in a string
28 32
 -- @tparam string text Input string.
29 33
 -- @treturn int Number of lines.
34
+-- @staticfct gears.string.linecount
30 35
 function gstring.linecount(text)
31 36
     return select(2, text:gsub('\n', '\n')) + 1
32 37
 end
33 38
 
34
---- Split a string into multiple lines
39
+--- Split a string into multiple lines.
35 40
 -- @param text String to wrap.
36 41
 -- @param width Maximum length of each line. Default: 72.
37 42
 -- @param indent Number of spaces added before each wrapped line. Default: 0.
38 43
 -- @return The string with lines wrapped to width.
44
+-- @staticfct gears.string.linewrap
39 45
 function gstring.linewrap(text, width, indent)
40 46
     text = text or ""
41 47
     width = width or 72
@@ -62,8 +60,7 @@ end
62 60
 --- Escape all special pattern-matching characters so that lua interprets them
63 61
 -- literally instead of as a character class.