Merge branch 'master' into hotkeys-popup-better-split-key-labels

.travis.yml

@@ -239,7 +239,9 @@ script:
         && grep -q 'May not access' lib/beautiful/init.lua
     fi
   - |
-    set -e
+    trap 'echo ERR CODE $? from $BASH_COMMAND : $LINENO' ERR
+    trap 'echo EXIT CODE $? from $BASH_COMMAND : $LINENO' EXIT
+    set -ex
     if [ -n "$BUILD_IN_DIR" ]; then
       # Explicitly remove the Makefile to not build from the src dir accidentally.
       rm Makefile
@@ -289,7 +291,7 @@ script:
     fi
   - |
     if [ "$TEST_PREV_COMMITS" = 1 ] && ! [ "$TRAVIS_PULL_REQUEST" = false ]; then
-      set -e
+      set -ex
       # Check each commit separately (to make git-bisect less annoying).
       # Fix Travis' commit range (https://github.com/travis-ci/travis-ci/issues/4596).
       commit_range="${TRAVIS_COMMIT_RANGE/.../..}"
@@ -330,8 +332,11 @@ after_success:
   - if [ "$BUILD_APIDOC" = "true" ]; then build-utils/travis-apidoc.sh; fi
   # Push code coverage information
   - |
-    set -e
+    trap 'echo ERR CODE $? from $BASH_COMMAND : $LINENO' ERR
+    trap 'echo EXIT CODE $? from $BASH_COMMAND : $LINENO' EXIT
+    set -ex
     if [ "$DO_COVERAGE" = "coveralls" ]; then
       test -f build/luacov.stats.out || { echo 'build/luacov.stats.out does not exist.'; return 1; }
       luacov-coveralls --verbose --merge
     fi
+  - echo "The build finished normally"

CMakeLists.txt

@@ -412,14 +412,14 @@ if ("${TEST_MANUAL_SCREENS}" MATCHES "1")
 endif()
 
 add_custom_target(check-integration
-    ${CMAKE_COMMAND} -E env CMAKE_BINARY_DIR='${CMAKE_BINARY_DIR}' ${TESTS_RUN_ENV} ./tests/run.sh \$\${TEST_RUN_ARGS:--W}
+    ${CMAKE_COMMAND} -E env CMAKE_BINARY_DIR='${CMAKE_BINARY_DIR}' LUA='${LUA_EXECUTABLE}' ${TESTS_RUN_ENV} ./tests/run.sh \$\${TEST_RUN_ARGS:--W}
     WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
     COMMENT "Running integration tests"
     DEPENDS ${PROJECT_AWE_NAME}
     USES_TERMINAL)
 add_dependencies(check-integration test-gravity)
 add_custom_target(check-themes
-    ${CMAKE_COMMAND} -E env CMAKE_BINARY_DIR='${CMAKE_BINARY_DIR}' ${TESTS_RUN_ENV} ./tests/themes/run.sh
+    ${CMAKE_COMMAND} -E env CMAKE_BINARY_DIR='${CMAKE_BINARY_DIR}' LUA='${LUA_EXECUTABLE}' ${TESTS_RUN_ENV} ./tests/themes/run.sh
     WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
     COMMENT "Testing themes"
     USES_TERMINAL
@@ -427,7 +427,7 @@ add_custom_target(check-themes
 add_dependencies(check check-themes)
 
 add_custom_target(check-requires
-    lua "${CMAKE_SOURCE_DIR}/build-utils/check_for_invalid_requires.lua"
+    ${LUA_EXECUTABLE} "${CMAKE_SOURCE_DIR}/build-utils/check_for_invalid_requires.lua"
     WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
     COMMENT "Checking use of require()"
     USES_TERMINAL

awesome.c

@@ -645,7 +645,7 @@ main(int argc, char **argv)
 
     /* Parse `rc.lua` to see if it has an AwesomeWM modeline */
     if (!(default_init_flags & INIT_FLAG_FORCE_CMD_ARGS))
-        options_init_config(awesome_argv[0], confpath, &default_init_flags, &searchpath);
+        options_init_config(&xdg, awesome_argv[0], confpath, &default_init_flags, &searchpath);
 
     /* Setup pipe for SIGCHLD processing */
     {

awesomeConfig.cmake

@@ -33,6 +33,7 @@ macro(a_find_program var prg req)
     endif()
 endmacro()
 
+a_find_program(LUA_EXECUTABLE lua TRUE)
 a_find_program(GIT_EXECUTABLE git FALSE)
 # programs needed for man pages
 a_find_program(ASCIIDOCTOR_EXECUTABLE asciidoctor FALSE)
@@ -374,7 +375,7 @@ add_custom_command(TARGET setup_directories
 
 add_custom_command(
         OUTPUT ${BUILD_DIR}/docs/06-appearance.md
-        COMMAND lua ${SOURCE_DIR}/docs/06-appearance.md.lua
+        COMMAND ${LUA_EXECUTABLE} ${SOURCE_DIR}/docs/06-appearance.md.lua
         ${BUILD_DIR}/docs/06-appearance.md
         DEPENDS
             lgi-check-run
@@ -385,7 +386,7 @@ add_custom_command(
 foreach(RULE_TYPE client tag screen notification)
     add_custom_command(
         OUTPUT ${BUILD_DIR}/docs/common/${RULE_TYPE}_rules_index.ldoc
-        COMMAND lua ${SOURCE_DIR}/docs/build_rules_index.lua
+        COMMAND ${LUA_EXECUTABLE} ${SOURCE_DIR}/docs/build_rules_index.lua
             ${BUILD_DIR}/docs/common/${RULE_TYPE}_rules_index.ldoc
             ${RULE_TYPE}
 
@@ -405,7 +406,7 @@ endforeach()
 add_custom_command(
         OUTPUT ${BUILD_DIR}/awesomerc.lua ${BUILD_DIR}/docs/05-awesomerc.md
             ${BUILD_DIR}/script_files/rc.lua
-        COMMAND lua ${SOURCE_DIR}/docs/05-awesomerc.md.lua
+        COMMAND ${LUA_EXECUTABLE} ${SOURCE_DIR}/docs/05-awesomerc.md.lua
         ${BUILD_DIR}/docs/05-awesomerc.md ${SOURCE_DIR}/awesomerc.lua
         ${BUILD_DIR}/awesomerc.lua
         ${BUILD_DIR}/script_files/rc.lua
@@ -414,7 +415,7 @@ add_custom_command(
 
 add_custom_command(
         OUTPUT ${BUILD_DIR}/script_files/theme.lua
-        COMMAND lua ${SOURCE_DIR}/docs/sample_theme.lua ${BUILD_DIR}/script_files/
+        COMMAND ${LUA_EXECUTABLE} ${SOURCE_DIR}/docs/sample_theme.lua ${BUILD_DIR}/script_files/
 )
 
 # Create a target for the auto-generated awesomerc.lua and other files

build-utils/travis-apidoc.sh

@@ -98,15 +98,18 @@ git commit -m "[relevant] $COMMIT_MSG"
 mv .git ../doc
 cd ../doc
 git add --all .
-git commit -m "[boilerplate] $COMMIT_MSG"
+BOILERPLATE_FAILED=0
+git commit -m "[boilerplate] $COMMIT_MSG" || export BOILERPLATE_FAILED=1
 
 # Reorder/swap commits, to have "relevant" after "boilerplate".
 # This makes it show up earlier in the Github interface etc.
-git tag _old
+if [  "$BOILERPLATE_FAILED" == "0" ]; then
-git reset --hard HEAD~2
+    git tag _old
-git cherry-pick _old _old~1
+    git reset --hard HEAD~2
-RELEVANT_REV="$(git rev-parse --short HEAD)"
+    git cherry-pick _old _old~1
-git tag -d _old
+    RELEVANT_REV="$(git rev-parse --short HEAD)"
+    git tag -d _old
+fi
 
 git checkout "$BRANCH"
 OLD_REV="$(git rev-parse --short HEAD)"

docs/01-readme.md

@@ -6,36 +6,39 @@ Awesome is a highly configurable, next generation framework window manager for X
 
 ## Building and installation
 
-After extracting the dist tarball, run:
+After extracting the dist tarball or cloning the repository, run:
 
-    make
+```sh
+make
+sudo make install
+```
 
-This will create a build directory, run `cmake` in it and build Awesome.
+This will
 
-After building is finished, you can either install via `make install`:
+1. create a build directory at `./build`,
+2. run `cmake`,
+3. build Awesome and
+4. install it to the default prefix path `/usr/local`.
 
-    make install  # you might need root permissions
+Alternatively to the above, you can generate a `.deb` or `.rpm` package, for easy installation management:
 
-or by auto-generating a .deb or .rpm package, for easy removal later on:
+```sh
+make package
 
-    make package
+sudo dpkg -i awesome-x.y.z.deb
+# or
+sudo rpm -Uvh awesome-x.y.z.rpm
+```
 
-    sudo dpkg -i awesome-x.y.z.deb
+### Advanced options and testing
-    # or
-    sudo rpm -Uvh awesome-x.y.z.rpm
-
-NOTE: Awesome uses [`cmake`](https://cmake.org) to build. In case you want to
-pass arguments to `cmake`, please use the `CMAKE_ARGS` environment variable. For
-instance:
-
-    CMAKE_ARGS="-DCMAKE_INSTALL_PREFIX=/opt/awesome" make
 
+A full list of dependencies, more advanced build options, as well as instructions on how to use the test suite can be found [here](https://awesomewm.org/apidoc/10-building-and-testing.md.html).
 
 ### Installing current git master as a package receipts
 
 #### Arch Linux AUR
 
-```
+```sh
 sudo pacman -S --needed base-devel git
 git clone https://aur.archlinux.org/awesome-git.git
 cd awesome-git
@@ -44,7 +47,7 @@ makepkg -fsri
 
 #### Debian-based
 
-```
+```sh
 sudo apt build-dep awesome
 git clone https://github.com/awesomewm/awesome
 cd awesome
@@ -52,76 +55,22 @@ make package
 sudo apt install *.deb
 ```
 
-
-### Build dependencies
-
-Awesome has the following dependencies (besides a more-or-less standard POSIX
-environment):
-
-- [CMake >= 3.0.0](https://cmake.org)
-- [Lua >= 5.1.0](https://www.lua.org) or [LuaJIT](http://luajit.org)
-- [LGI >= 0.8.0](https://github.com/pavouk/lgi)
-- [xproto >= 7.0.15](https://www.x.org/archive//individual/proto/)
-- [libxcb >= 1.6](https://xcb.freedesktop.org/) with support for the RandR, XTest, Xinerama, SHAPE and
-  XKB extensions
-- [libxcb-cursor](https://xcb.freedesktop.org/)
-- [libxcb-util >= 0.3.8](https://xcb.freedesktop.org/)
-- [libxcb-keysyms >= 0.3.4](https://xcb.freedesktop.org/)
-- [libxcb-icccm >= 0.3.8](https://xcb.freedesktop.org/)
-- [libxcb-xfixes](https://xcb.freedesktop.org/)
-- [xcb-util-xrm >= 1.0](https://github.com/Airblader/xcb-util-xrm)
-- [libxkbcommon](http://xkbcommon.org/) with X11 support enabled
-- [libstartup-notification >=
-  0.10](https://www.freedesktop.org/wiki/Software/startup-notification/)
-- [cairo](https://www.cairographics.org/) with support for XCB and GObject
-  introspection
-- [Pango](http://www.pango.org/) with support for Cairo and GObject
-  introspection
-- [GLib >= 2.40](https://wiki.gnome.org/Projects/GLib) with support for GObject
-  introspection
-- [GIO](https://developer.gnome.org/gio/stable/) with support for GObject
-  introspection
-- [GdkPixbuf](https://wiki.gnome.org/Projects/GdkPixbuf)
-- libX11 with xcb support
-- [Imagemagick's convert utility](http://www.imagemagick.org/script/index.php)
-- [libxdg-basedir >= 1.0.0](https://github.com/devnev/libxdg-basedir)
-
-Additionally, the following optional dependencies exist:
-
-- [DBus](https://www.freedesktop.org/wiki/Software/dbus/) for DBus integration
-  and the `awesome-client` utility
-- [asciidoctor](https://asciidoctor.org/) for generating man pages
-- [gzip](http://www.gzip.org/) for compressing man pages
-- [ldoc >= 1.4.5](https://stevedonovan.github.io/ldoc/) for generating the
-  documentation
-- [busted](https://olivinelabs.com/busted/) for running unit tests
-- [luacheck](https://github.com/mpeterv/luacheck) for static code analysis
-- [LuaCov](https://keplerproject.github.io/luacov/) for collecting code coverage
-  information
-- libexecinfo on systems where libc does not provide `backtrace_symbols()` to
-  generate slightly better backtraces on crashes
-- `Xephyr` or `Xvfb` for running integration tests
-- [GTK+ >= 3.10](https://www.gtk.org/) for `./themes/gtk/`
-- [xcb-errors](https://gitlab.freedesktop.org/xorg/lib/libxcb-errors) for
-  pretty-printing of X11 errors
-- [libRSVG](https://wiki.gnome.org/action/show/Projects/LibRsvg) for displaying
-  SVG files without scaling artifacts
-- [wmctrl](http://tripie.sweb.cz/utils/wmctrl) for testing WM interactions
-  with external actions
-- [xterm](https://invisible-island.net/xterm/) for various test cases
-
 ## Running Awesome
 
 You can directly select Awesome from your display manager. If not, you can
 add the following line to your `.xinitrc` to start Awesome using `startx`
 or to `.xsession` to start Awesome using your display manager:
 
-    exec awesome
+```sh
+exec awesome
+```
 
 In order to connect Awesome to a specific display, make sure that
 the `DISPLAY` environment variable is set correctly, e.g.:
 
-    DISPLAY=foo.bar:1 exec awesome
+```sh
+DISPLAY=foo.bar:1 exec awesome
+```
 
 (This will start Awesome on display `:1` of the host foo.bar.)
 
@@ -145,12 +94,16 @@ problem.
 
 You can call `awesome` with `gdb` like this:
 
-    DISPLAY=:2 gdb awesome
+```sh
+DISPLAY=:2 gdb awesome
+```
 
 Then in `gdb` set any arguments and run it:
 
-    (gdb) set args --replace
+```
-    (gdb) run
+(gdb) set args --replace
+(gdb) run
+```
 
 ## Asking questions
 

docs/03-declarative-layout.md

@@ -1,7 +1,13 @@
-# The AwesomeWM widget system
+# The Widget system
 
 This document explains how to define, place and manage widgets.
 
+## The default configuration
+
+This is what the widgets present in the default configuration are named:
+
+@DOC_awful_popup_defaultconfig_EXAMPLE@
+
 ## The default widgets
 
 ### Widgets
@@ -28,7 +34,59 @@ configurable rules.
 
 @DOC_layout_WIDGET_LIST@
 
-### Other
+### Awful widgets
+
+This modules contains the higher level window manager widgets. Since most of them
+are used by the default config, here is how it maps:
+
+@DOC_awful_wibar_defaultwibar_EXAMPLE@
+
+@DOC_awidget_WIDGET_LIST@
+
+### Titlebar widgets
+
+The titlebar comes with some convinient default widgets. It simplify the most
+basic "Windows/macOS" like titlebars.
+
+@DOC_awful_titlebar_defaulttitlebar_EXAMPLE@
+
+Note that titlebars can also be added on
+each side. This is how "active" titlebars (click to resize) can be implemented.
+The default `rc.lua` does not add active borders:
+
+![](../images/client_geo.svg)
+
+<table class="widget_list" border="1">
+ <tr>
+   <th>Widget</th><th>Description</th>
+ </tr>
+ <tr>
+  <td>`awful.titlebar.widget.iconwidget`</td><td>The client icon (see `client.icon`)</td>
+ </tr>
+ <tr>
+  <td>`awful.titlebar.widget.titlewidget`</td><td>The client title (see `client.name`)</td>
+ </tr>
+ <tr>
+  <td>`awful.titlebar.widget.floatingbutton`</td><td> Toggle the floating (toggled) vs. tiling mode (untoggled). </td>
+ </tr>
+ <tr>
+  <td>`awful.titlebar.widget.maximizedbutton`</td><td>Toggle the maximized mode (toggled). Note that this is the<br/>"full" maximized mode, not vertical or horizontal maximization.<br/>See `client.maximized`.</td>
+ </tr>
+ <tr>
+  <td>`awful.titlebar.widget.stickybutton`</td><td>When toggled, a client will be displayed in all (screen) tags. See `client.sticky`)</td>
+ </tr>
+ <tr>
+  <td>`awful.titlebar.widget.ontopbutton`</td><td>When toggled, the client will be part of the `ontop` layer (see `client.ontop`).</td>
+ </tr>
+ <tr>
+  <td>`awful.titlebar.widget.closebutton`</td><td></td>
+ </tr>
+ <tr>
+  <td>`titlebar.widget.minimizebutton`</td><td></td>
+ </tr>
+</table>
+
+### Notification widgets
 
 Notifications also have their own widgets.
 

docs/05-awesomerc.md.lua

@@ -18,10 +18,15 @@ The Awesome API is distributed across many libraries (also called modules).
 Here are the modules that we import:
 
 <table class='widget_list' border=1>
+  <tr style='font-weight: bold;'>
+   <th align='center'>Library</th>
+   <th align='center'>Description</th>
+  </tr>
   <tr><td>`gears`</td><td>Utilities such as color parsing and objects</td></tr>
   <tr><td>`wibox`</td><td>Awesome own generic widget framework</td></tr>
   <tr><td>`awful`</td><td>Everything related to window managment</td></tr>
   <tr><td>`naughty`</td><td>Notifications</td></tr>
+  <tr><td>`ruled`</td><td>Define declarative rules on various events</td></tr>
   <tr><td>`menubar`</td><td>XDG (application) menu implementation</td></tr>
   <tr><td>`beautiful`</td><td>Awesome theme module</td></tr>
 </table>

docs/07-my-first-awesome.md

@@ -25,10 +25,10 @@ have not opened any programs. On the top right you see the time/date and a
 symbol showing the current layout. You can also click on the symbol to change
 the active layout.
 
-One of the big advantages of Awesome over other tiling window managers is its good
+One of the big advantages of Awesome over other tiling window managers is its
-mouse support. Awesome can act as a full floating window manager (almost like
+good mouse support. Awesome can act as a full floating window manager (almost
-openbox) if you want. For this basic tutorial we will mainly focus on keyboard
+like openbox) if you want. For this basic tutorial we will mainly focus on
-control, so let's learn some key bindings now.
+keyboard control, so let's learn some key bindings now.
 
 Let's open a terminal: press *Mod4+Enter*. Mod4 is your "Windows key", the key
 between Ctrl and Alt. You can change the modkey if you want, but we'll get to
@@ -65,20 +65,18 @@ overview now also provides a cheat sheet for controlling Vim.
 
 ## Change the theme
 
-Awesome has four themes you can choose from: *default*, *sky*, *xresources*, and
+Awesome has four builtin themes you can choose from: *default*, *sky*,
-*zenburn*.
+*xresources*, and *zenburn*.
 
-To change the theme, open your rc.lua and edit this line near the beginning of
+To change the theme, open your `rc.lua`, find this line near the beginning of
-the file:
+the file, and change `default` to one of the other values mentioned:
 
     beautiful.init(gears.filesystem.get_themes_dir() .. "default/theme.lua")
 
-For this tutorial we will stick with the default theme.
+However, for this tutorial we will copy and customize the default theme.
-
+Copy `/usr/share/awesome/themes/default/theme.lua` to `~/.config/awesome/`
-Now we will customize the theme. Copy
+and change the line shown above in `rc.lua` like this. Make sure to replace
-`/usr/share/awesome/themes/default/theme.lua` to `~/.config/awesome/` and change
+`USER` with your user name.
-the above line in your theme like this (remember to replace `USER` with your
-user name):
 
     beautiful.init("/home/USER/.config/awesome/theme.lua")
 
@@ -89,7 +87,9 @@ this line in your theme file:
 
     theme.wallpaper = themes_path.."default/background.png"
 
-The default uses a path relative to `themes_path` by using the `..` operator to join two strings together. To just set it to an absolute path for example, you could do:
+The default uses a path relative to `themes_path` by using the `..` operator to
+join two strings together. To just set it to an absolute path for example,
+you could do:
 
     theme.wallpaper = "/usr/share/backgrounds/my-awesome-wallpaper.png"
 

docs/08-client-layout-system.md

@@ -0,0 +1,54 @@
+# The AwesomeWM client layout system
+
+This document explains how to use clients layouts and how awesome manage them.
+
+**Client layout**  refers to the mechanism awesome uses to place client on the screen. The layout definition can be a basic system where clients are all *floating* like in a normal *DE* (eg GNOME, KDE, ...) or tiled on the screen like in *tilled window manager* (eg i3, BSPWM, ...). It is also possible to define complex client layout mixing both concepts and even implementing a *[stateful](https://en.wikipedia.org/wiki/State_(computer_science)) placement strategy*.
+
+Awesome WM manages client layouts per tag. It means each tag has its own layout selection and uses them independently from other tags. When multiple tags are selected at once, Awesome uses only client layouts from the first selected tag and apply it to all current clients.
+
+## Layouts configuration
+
+Layout can be configured by setting properties from the tag instance.
+
+Example of creating a new tag with client layout parameters:
+```lua
+awful.tag.add("My Tag", {
+    screen = screen.primary,
+    layout = awful.layout.suit.tile,
+    master_fill_policy = "master_width_factor",
+    gap_single_client = false,
+    gap = 15
+})
+```
+
+Example of changing client layout parameters on an existing tag:
+```lua
+-- Change the gap for the tag `my_tag`:
+my_tag.useless_gap = 10
+
+-- Change the master_width_factor for the tag `my_tag`:
+my_tag.master_width_factor = 0.5
+```
+
+Here is a list of common properties used to configure tags:
+
+<table class='widget_list' border=1>
+<tr>
+<th align='center'>Property</th>
+<th align='center'>Type</th>
+<th align='center'>Description</th>
+</tr>
+<tr><td>gap</td><td>number</td><td>The gap (spacing, also called useless_gap) between clients.</td></tr>
+<tr><td>gap_single_client</td><td>boolean</td><td>Enable gaps for a single client.</td></tr>
+<tr><td>master_fill_policy</td><td>string</td><td>Set size fill policy for the master client(s).</td></tr>
+<tr><td>master_count</td><td>integer</td><td>Set the number of master windows.</td></tr>
+<tr><td>icon</td><td>path or surface</td><td>Set the tag icon.</td></tr>
+<tr><td>column_count</td><td>integer</td><td>Set the number of columns.</td></tr>
+</table>
+
+
+## Creating new client layouts
+
+* arrange function (params definition)
+* needs a name property
+* mouse_resize_handler function

docs/10-building-and-testing.md

@@ -0,0 +1,142 @@
+# Building and Testing
+
+## Dependencies
+
+Awesome has the following dependencies (besides a more-or-less standard POSIX
+environment):
+
+- [CMake >= 3.0.0](https://cmake.org)
+- [Lua >= 5.1.0](https://www.lua.org) or [LuaJIT](http://luajit.org)
+- [LGI >= 0.8.0](https://github.com/pavouk/lgi)
+- [xproto >= 7.0.15](https://www.x.org/archive//individual/proto/)
+- [libxcb >= 1.6](https://xcb.freedesktop.org/) with support for the RandR, XTest, Xinerama, SHAPE and
+  XKB extensions
+- [libxcb-cursor](https://xcb.freedesktop.org/)
+- [libxcb-util >= 0.3.8](https://xcb.freedesktop.org/)
+- [libxcb-keysyms >= 0.3.4](https://xcb.freedesktop.org/)
+- [libxcb-icccm >= 0.3.8](https://xcb.freedesktop.org/)
+- [libxcb-xfixes](https://xcb.freedesktop.org/)
+- [xcb-util-xrm >= 1.0](https://github.com/Airblader/xcb-util-xrm)
+- [libxkbcommon](http://xkbcommon.org/) with X11 support enabled
+- [libstartup-notification >=
+  0.10](https://www.freedesktop.org/wiki/Software/startup-notification/)
+- [cairo](https://www.cairographics.org/) with support for XCB and GObject
+  introspection
+- [Pango](http://www.pango.org/) with support for Cairo and GObject
+  introspection
+- [GLib >= 2.40](https://wiki.gnome.org/Projects/GLib) with support for GObject
+  introspection
+- [GIO](https://developer.gnome.org/gio/stable/) with support for GObject
+  introspection
+- [GdkPixbuf](https://wiki.gnome.org/Projects/GdkPixbuf)
+- libX11 with xcb support
+- [Imagemagick's convert utility](http://www.imagemagick.org/script/index.php)
+- [libxdg-basedir >= 1.0.0](https://github.com/devnev/libxdg-basedir)
+
+Additionally, the following optional dependencies exist:
+
+- [DBus](https://www.freedesktop.org/wiki/Software/dbus/) for DBus integration
+  and the `awesome-client` utility
+- [asciidoctor](https://asciidoctor.org/) for generating man pages
+- [gzip](http://www.gzip.org/) for compressing man pages
+- [ldoc >= 1.4.5](https://stevedonovan.github.io/ldoc/) for generating the
+  documentation
+- [busted](https://olivinelabs.com/busted/) for running unit tests
+- [luacheck](https://github.com/mpeterv/luacheck) for static code analysis
+- [LuaCov](https://keplerproject.github.io/luacov/) for collecting code coverage
+  information
+- libexecinfo on systems where libc does not provide `backtrace_symbols()` to
+  generate slightly better backtraces on crashes
+- `Xephyr` or `Xvfb` for running integration tests
+- [GTK+ >= 3.10](https://www.gtk.org/) for `./themes/gtk/`
+- [xcb-errors](https://gitlab.freedesktop.org/xorg/lib/libxcb-errors) for
+  pretty-printing of X11 errors
+- [libRSVG](https://wiki.gnome.org/action/show/Projects/LibRsvg) for displaying
+  SVG files without scaling artifacts
+- [wmctrl](http://tripie.sweb.cz/utils/wmctrl) for testing WM interactions
+  with external actions
+- [xterm](https://invisible-island.net/xterm/) for various test cases
+
+## Building
+
+With all dependencies installed, run the following commands within the root of the repository to build and install Awesome on your system:
+
+```sh
+make
+sudo make install
+```
+
+### Create packages
+
+To ease installation management, you can pack Awesome into `.deb` or `.rpm` packages. The following command will build the correct package for your system's package manager:
+
+```sh
+make package
+```
+
+To install the package, run one of the following commands:
+
+```sh
+sudo dpkg -i awesome-x.y.z.deb
+# or
+sudo rpm -Uvh awesome-x.y.z.rpm
+```
+
+### Customizing build options
+
+Awesome allows customizing various aspects of the build process through CMake variables. To change these variables, pass the `CMAKE_ARGS` environment variable to `make` with CMake flags as content (see `cmake -h`).
+
+Here is an example:
+
+```sh
+CMAKE_ARGS="-DLUA_EXECUTABLE=/usr/bin/lua5.3" make
+```
+
+**Note:**
+
+CMake arguments only need to be specified on the first run of `make` or after `make distclean`.
+
+#### Skip documentation
+
+The CMake variables `GENERATE_DOC` and `GENERATE_MANPAGES` toggle generation of HTML documentation and man pages respectively. They are enabled by default but can be set to `OFF`.
+
+```sh
+CMAKE_ARGS="-DGENERATE_DOC=OFF -DGENERATE_MANPAGES=OFF" make
+```
+
+#### Change the Lua version
+
+Both the build steps and the final binary require a working Lua interpreter. To change the Lua interpreter that both the build process and Awesome should use, specify an absolute path to a `lua` binary for `LUA_EXECUTABLE` and values that match the binary's version for `LUA_LIBRARY` and `LUA_INCLUDE_DIR`.
+
+Example to build on Arch Linux:
+
+```sh
+CMAKE_ARGS="-DLUA_EXECUTABLE=/usr/bin/lua5.3 -DLUA_LIBRARY=/usr/lib/liblua.so.5.3 -DLUA_INCLUDE_DIR=/usr/include/lua5.3" make
+```
+
+#### Additional options
+
+Additional variables can be found through CMake. Run the following command to print a list of all available variables, including the ones explained above:
+
+```sh
+cmake -B build -L
+```
+
+## Testing
+
+Once Awesome has been built, you can run various test suites to verify functionality for both the binary and the Lua library. Make sure to install applicable dependencies as outlined at the top.
+
+**Full test suite:**
+
+```sh
+make check
+```
+
+Individual test categories can be run as well:
+
+* `make check-integration`: Run integration tests within a Xephyr session.
+* `make check-qa`: Run `luacheck` against the Lua library
+* `make check-unit`: Run unit tests with `busted` against the Lua library. You can also run `busted <options> ./spec` if you want to specify options for `busted`.
+* `make check-requires`: Check for invalid `require()` calls.
+* `make check-examples`: Run integration tests within the examples in `./tests/examples`.
+* `make check-themes`: Test themes.

docs/16-using-cairo.md

@@ -147,7 +147,7 @@ some examples. Here is the most simple example you can get:
     local cr  = cairo.Context(img)
 
     -- Set a red source
-    cr:set_source(1, 0, 0)
+    cr:set_source_rgb(1, 0, 0)
     -- Alternative:
     cr:set_source(gears.color("#ff0000"))
 

docs/89-NEWS.md

@@ -45,6 +45,7 @@ This document was last updated at commit v4.3-197-g9085ed631.
   Lua code using `io.popen`. Usage of `io.popen` is still strongly discouraged.
 * `wibox{ input_passthrough = true }` now works correctly. Previously, the
   property could only be set on already-constructed wiboxes.
+* Remove unused first parameter from multiple widget constructors: `wibox.container.place`,  `wibox.container.radialprogressbar`,  `wibox.layout.stack`,  `wibox.widget.slider`.
 
 ## Behavior changes
 

docs/common/glib_timedate_format.ldoc

@@ -0,0 +1,28 @@
+--<table class='widget_list' border=1>
+-- <tr>
+--   <th align='center'>Format</th>
+--   <th align='center'>Description</th>
+-- </tr>
+--   <tr><td>%a</td><td>The abbreviated weekday name according to the current locale</td></tr>
+--   <tr><td>%A</td><td>the full weekday name according to the current locale</td></tr>
+--   <tr><td>%b</td><td>The abbreviated month name according to the current locale</td></tr>
+--   <tr><td>%B</td><td>The full month name according to the current locale</td></tr>
+--   <tr><td>%d</td><td>The day of the month as a decimal number (range 01 to 31)</td></tr>
+--   <tr><td>%e</td><td>The day of the month as a decimal number (range 1 to 31)</td></tr>
+--   <tr><td>%F</td><td>Equivalent to %Y-%m-%d (the ISO 8601 date format)</td></tr>
+--   <tr><td>%H</td><td>The hour as a decimal number using a 24-hour clock (range 00 to 23)</td></tr>
+--   <tr><td>%I</td><td>The hour as a decimal number using a 12-hour clock (range 01 to 12)</td></tr>
+--   <tr><td>%k</td><td>The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank</td></tr>
+--   <tr><td>%l</td><td>The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank</td></tr>
+--   <tr><td>%m</td><td>The month as a decimal number (range 01 to 12)</td></tr>
+--   <tr><td>%M</td><td>The minute as a decimal number (range 00 to 59)</td></tr>
+--   <tr><td>%p</td><td>Either "AM" or "PM" according to the given time value, or the corresponding strings for the current locale. Noon is treated as "PM" and midnight as "AM".</td></tr>
+--   <tr><td>%P</td><td>Like %p but lowercase: "am" or "pm" or a corresponding string for the current locale</td></tr>
+--   <tr><td>%r</td><td>The time in a.m. or p.m. notation</td></tr>
+--   <tr><td>%R</td><td>The time in 24-hour notation (%H:%M)</td></tr>
+--   <tr><td>%S</td><td>The second as a decimal number (range 00 to 60)</td></tr>
+--   <tr><td>%T</td><td>The time in 24-hour notation with seconds (%H:%M:%S)</td></tr>
+--   <tr><td>%y</td><td>The year as a decimal number without the century</td></tr>
+--   <tr><td>%Y</td><td>The year as a decimal number including the century</td></tr>
+--   <tr><td>%%</td><td>A literal % character</td></tr>
+-- </table>

docs/config.ld

@@ -20,7 +20,7 @@ merge=true
 use_markdown_titles=true
 wrap=true
 full_description = [[
-Welcome to the documentation for the awesome window manager. Below you find an
+Welcome to the documentation for the Awesome window manager. Below you find an
 overview of the individual parts which links to the full documentation.
 
 If you are a new user, you may want to read @{07-my-first-awesome.md} to get
@@ -28,6 +28,49 @@ started. In @{05-awesomerc.md}, the default configuration is explained.
 
 If you already used awesome in the past, @{89-NEWS.md} and @{17-porting-tips.md}
 should be useful for you.
+
+### Default configuration components name:
+
+<center><img src="../doc/images/AUTOGEN_awful_popup_defaultconfig.svg"></center>
+
+### Guides
+
+<div class="index_guides">
+    <div>
+        <a href="../doc/documentation/07-my-first-awesome.md.html">Getting started</a>
+        <a href="../doc/documentation/90-FAQ.md.html">FAQ</a>
+        <a href="../doc/documentation/01-readme.md.html">Read me</a>
+        <a href="../doc/documentation/89-NEWS.md.html">NEWS</a>
+    </div>
+    <div>
+        <a href="../doc/documentation/03-declarative-layout.md.html">The widget system</a>
+        <a href="../doc/documentation/09-options.md.html">Startup options</a>
+        <a href="../doc/documentation/05-awesomerc.md.html">The default rc.lua</a>
+        <a href="../doc/documentation/08-client-layout-system.md.html">Window management</a>
+    </div>
+</div>
+
+## Major libraries
+
+AwesomeWM ship multiple libraries. Here is an overview of the purpose and scope
+of those libraries.
+
+<table class='widget_list' border=1>
+  <tr style='font-weight: bold;'>
+   <th align='center'>Library</th>
+   <th align='center'>Description</th>
+  </tr>
+  <tr><td>`gears`</td><td>Utilities such as color parsing and objects</td></tr>
+  <tr><td>`wibox`</td><td>Awesome own generic widget framework</td></tr>
+  <tr><td>`awful`</td><td>Everything related to window managment</td></tr>
+  <tr><td>`awful.widget`</td><td>Window management related widgets</td></tr>
+  <tr><td>`awful.layout`</td><td>The default stateless client tiling module.</td></tr>
+  <tr><td>`ruled`</td><td>Define declarative rules on various events</td></tr>
+  <tr><td>`naughty`</td><td>Notifications</td></tr>
+  <tr><td>`menubar`</td><td>XDG (application) menu implementation</td></tr>
+  <tr><td>`beautiful`</td><td>Awesome theme module</td></tr>
+</table>
+
 ]]
 topics={
     '00-authors.md',
@@ -38,7 +81,9 @@ topics={
     '05-awesomerc.md',
     '06-appearance.md',
     '07-my-first-awesome.md',
+    '08-client-layout-system.md',
     '09-options.md',
+    '10-building-and-testing.md',
     '16-using-cairo.md',
     '17-porting-tips.md',
     '90-FAQ.md',
@@ -411,6 +456,25 @@ add_custom_tag {
     },
 }
 
+-- Define the supermodule class.
+-- This tag should be used at the module level. All properties from the
+-- supermodule will be recursively added to the module by our ldoc template.
+-- @supermodule supermodule
+add_custom_tag {
+    name = "supermodule",
+    hidden = true,
+    auto_subtags = false
+}
+
+-- Mark the item ad hidden.
+-- This tag should be used to hide items from the documentation.
+-- @hidden
+add_custom_tag {
+    name = "hidden",
+    hidden = true,
+    auto_subtags = false
+}
+
 -- More fitting section names
 kind_names={topic='Documentation', module='Libraries', script='Sample files'}
 

docs/ldoc.css

@@ -482,3 +482,53 @@ pre .url { color: #272fc2; text-decoration: underline; }
     color: rgb(128, 128, 128);
     border-radius: 7px;
 }
+
+.index_guides div {
+    margin: 0 auto;
+    display: table;
+    margin-bottom: 10px;
+}
+
+.index_guides div a {
+    display: inline-block;
+    border: solid 1px #cccccc;
+    width: 200px;
+    margin-left: 10px;
+    margin-right: 10px;
+    text-align: center;
+    padding-top: 20px;
+    padding-bottom: 20px;
+}
+
+.index_guides div a:hover {
+    background-color: #99b3ec;
+}
+
+/* Inheritance diagram */
+.inheritance .inheritance__level {
+    list-style: none;
+}
+
+.inheritance .inheritance__level--root {
+    padding-left: 0;
+}
+
+.inheritance .inheritance__level__node::before {
+    content: "↳";
+}
+
+.inheritance .inheritance__level__node--root::before {
+    /* simulate the spacing of the arrow character */
+    content: "   ";
+    white-space: pre;
+}
+
+.extra-header {
+    display: flex;
+    flex-direction: row;
+    flex-wrap: wrap;
+}
+
+.extra-header__section {
+    flex-grow: 1;
+}

docs/ldoc.ltp

@@ -43,6 +43,80 @@
 # local html_space = function(s) return s:gsub(" ", "%%20") end
 # local no_underscores = function(s) return s:gsub("_", " ") end
 
+# --------- modules hierarchy -------------
+# local hierarchy = {}
+# local curr = module
+# while curr do
+#     hierarchy[#hierarchy + 1] = curr
+#     -- no need to do anything more if there is no explicite @supermodule
+#     if not curr.tags.supermodule then break end
+#     local super = curr.tags.supermodule[1] -- only consider one way inheritance
+#     local found = false
+#     for kind, mods, type in ldoc.kinds() do
+#         for mod in mods() do
+#             local name = display_name(mod)
+#             if name == super then
+#                 curr = mod
+#                 found = true
+#             end
+#             if found then break end
+#         end
+#         if found then break end
+#     end
+#     if not found then curr = nil end
+# end
+
+# --------- merge modules content with supermodules -------------
+# local all_module_kinds = {}
+# if module then
+# for kind,items in module.kinds() do
+#     local myitems = {}
+#     for item in items() do
+#       myitems[#myitems + 1] = item
+#      end
+#     all_module_kinds[#all_module_kinds + 1] = { kind = kind,  items = myitems }
+# end
+# local filtered_kinds = { "Constructors", "Static module functions",
+#   "Functions", "Methods", "lib.gears.object.properties Functions" }
+# for supermodule in iter(hierarchy) do
+#     for kind,items in supermodule.kinds() do
+#         local ignored = false
+#         for _,filtered in ldoc.pairs(filtered_kinds) do
+#             if kind == filtered then
+#                 ignored = true
+#                 break
+#             end
+#         end
+#         if not ignored then
+#             local curr_kind = nil
+#             for k in iter(all_module_kinds) do
+#                 if k.kind == kind then
+#                     curr_kind = k
+#                     break
+#                 end
+#             end
+#             if not curr_kind then
+#                 curr_kind  = { kind = kind, items = {} }
+#                 all_module_kinds[#all_module_kinds + 1] = curr_kind
+#             end
+#             for item in items() do
+#                 local tobeadded = true
+#                 for i in iter(curr_kind.items) do
+#                     if item.name == i.name then
+#                         tobeadded = false
+#                         break
+#                     end
+#                 end
+#                 if tobeadded then
+#                     item.inherited = true -- force inherited status
+#                     curr_kind.items[#curr_kind.items + 1] = item
+#                 end
+#             end
+#         end
+#     end
+# end
+# end
+
 <!-- Menu -->
 
 <div id="navigation">
@@ -59,7 +133,8 @@
 # if module and not ldoc.no_summary and #module.items > 0 then
 <h2>Contents</h2>
 <ul>
-# for kind,items in module.kinds() do
+# for k in iter(all_module_kinds) do
+#  local kind = k.kind
 #  if not kind:match("^ldoc_skip") then
 <li><a href="#$(no_spaces(kind))">$(kind)</a></li>
 # end
@@ -109,18 +184,6 @@
 <h1>Module: <code>$(module.name)</code></h1>
 <p>$(M(module.summary,module))</p>
 <p>$(M(module.description,module))</p>
-#   if module.tags.include then
-        $(M(ldoc.include_file(module.tags.include)))
-#   end
-#   if module.see then
-#     local li,il = use_li(module.see)
-    <h3>See also:</h3>
-    <ul>
-#     for see in iter(module.see) do
-         $(li)<a href="$(ldoc.href(see))">$(see.label)</a>$(il)
-#    end -- for
-    </ul>
-#   end -- if see
 #   if module.usage then
 #     local li,il = use_li(module.usage)
     <h3>Usage:</h3>
@@ -130,20 +193,70 @@
 #     end -- for
     </ul>
 #   end -- if usage
+    <div class="extra-header">
+# if module.tags.supermodule then
+  <div class="extra-header__section">
+    <h3>Class Hierarchy</h3>
+    <div class="inheritance">
+# local function draw_hierary_recursifly(i)
+#   local is_root_level = (i == #hierarchy)
+    <ul class="inheritance__level $(is_root_level and 'inheritance__level--root' or '')">
+        <li class="inheritance__level__node $(is_root_level and 'inheritance__level__node--root' or '')">
+#   local mod = hierarchy[i]
+#   local name = display_name(hierarchy[i])
+#   if mod == module then
+            <strong>$(name)</strong>
+#   else
+            <a href="$(ldoc.ref_to_module(mod))">$(name)</a>
+#   end
+        </li>
+#   if i > 1 then
+        <li>
+#           draw_hierary_recursifly(i - 1)
+        </li>
+#   end
+    </ul>
+# end -- function draw_hierary_recursifly
+# draw_hierary_recursifly(#hierarchy)
+    </div>
+  </div>
+# end -- module.tags.supermodule
+
+#   if module.tags.include then
+        $(M(ldoc.include_file(module.tags.include)))
+#   end
+
 #   if module.info then
+  <div class="extra-header__section">
     <h3>Info:</h3>
     <ul>
 #     for tag, value in module.info:iter() do
-        <li><strong>$(tag)</strong>: $(M(value,module))</li>
+            <li><strong>$(tag)</strong>: $(M(value,module))</li>
 #     end
     </ul>
+  </div>
 #   end -- if module.info
 
+#   if module.see then
+  <div class="extra-header__section">
+#     local li,il = use_li(module.see)
+#     local list_or_p =(#module.see > 1) and 'ul' or 'p'
+    <h3>See also:</h3>
+    <$(list_or_p)>
+#     for see in iter(module.see) do
+         $(li)<a href="$(ldoc.href(see))">$(see.label)</a>$(il)
+#    end -- for
+    </$(list_or_p)>
+  </div>
+#   end -- if module.see
+</div>
+
 
 # if not ldoc.no_summary then
 # -- bang out the tables of item types for this module (e.g Functions, Tables, etc)
 # local last_kind = ""
-# for kind,items in module.kinds() do
+# for k in iter(all_module_kinds) do
+#  local kind = k.kind
 #  if not kind:match("^ldoc_skip") then
 #   if last_kind ~= "" then
 </table>
@@ -151,8 +264,9 @@
 <h2><a href="#$(no_spaces(kind))">$(kind)</a></h2>
 <table class="function_list">
 #  end
-#  for item in items() do
+#  for item in iter(k.items) do if not item.tags.hidden then
 #   local dn = display_name(item)
+#   local inherited = (item.baseclass ~= module.name)
 #   if item.sanitize_type then item.sanitize_type(item, ldoc) end
     <tr>
 #   if item.display_type and not item.compact_signature then
@@ -166,14 +280,14 @@
 #     end
       </td>
 #   end
-      <td colspan="$(item.inherited and 1 or 2)" class="summary">$(M(item.summary,item))</td>
+      <td colspan="$(inherited and 1 or 2)" class="summary">$(M(item.summary,item))</td>
-#   if item.inherited then
+#   if inherited then
-      <td class="baseclass" $(nowrap)>
+      <td class="baseclass" nowrap>
         Inherited from $(item.baseclass)
       </td>
 #   end
     </tr>
-#  end -- for items
+#  end end -- for items
 # last_kind = kind
 #end -- for kinds
 </table>
@@ -187,7 +301,8 @@
 # --- function parameters or table fields.
 # local show_return = not ldoc.no_return_or_parms
 # local show_parms, last_kind = show_return, ""
-# for kind, items in module.kinds() do
+# for k in iter(all_module_kinds) do
+#  local kind = k.kind
 #   local kitem = module.kinds:get_item(kind)
 #   local has_description = kitem and ldoc.descript(kitem) ~= ""
 #   if not kind:match("^ldoc_skip") then
@@ -211,7 +326,7 @@
 #  if not kind:match("^ldoc_skip") then
     <dl class="function">
 #  end
-#  for item in items() do
+#  for item in iter(k.items) do if not item.tags.hidden then
     <dt>
     <a name = "$(item.name)"></a>
     <strong>$(display_name(item))</strong>
@@ -225,8 +340,8 @@
     <span class="proptype">$(item.display_type)</span>
 #   end
     <span class="baseclass" $(nowrap)>
-#   if item.inherited then
+#   if item.baseclass ~= module.name then
-    &middot;&nbsp;Inherited from $(item.baseclass)
+    &middot;&nbsp;Inherited from $(M(item.baseclass, item))
 #   end
 #   if item.extra_summary then
 #       for _, col in ldoc.ipairs(item.extra_summary) do
@@ -371,7 +486,7 @@
     </span>
 
 </dd>
-# end -- for items
+# end end -- for items
 #  last_kind = kind
 # end -- for kinds
 </dl>

docs/widget_lists.cmake

@@ -52,5 +52,6 @@ endfunction()
 generate_widget_list( "container" )
 generate_widget_list( "layout"    )
 generate_widget_list( "widget"    )
+generate_widget_list( "awidget"   )
 
 # vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80:foldmethod=marker

lib/awful/client.lua

@@ -1531,13 +1531,13 @@ function client.object.activate(c, args)
     elseif new_args.action and new_args.action == "mouse_resize" then
         amousec.resize(c)
     elseif new_args.action and new_args.action == "mouse_center" then
-        local coords, geo = mouse.mouse.coords(), c:geometry()
+        local coords, geo = capi.mouse.coords(), c:geometry()
         coords.width, coords.height = 1,1
 
         if not grect.area_intersect_area(geo, coords) then
             -- Do not use `awful.placement` to avoid an useless circular
             -- dependency. Centering is *very* simple.
-            mouse.mouse.coords {
+            capi.mouse.coords {
                 x = geo.x + math.ceil(geo.width /2),
                 y = geo.y + math.ceil(geo.height/2)
             }

lib/awful/hotkeys_popup/keys/vim.lua

@@ -173,6 +173,16 @@ local vim_keys = {
             zR="open all",
         }
     }},
+
+    ["VIM: diff"] = {{
+        modifiers = {},
+        keys = {
+            ["do"]="diff obtain",
+            ["dp"]="diff put",
+            ["]c"]="jump next",
+            ["[c"]="jump previous",
+        }
+    }},
 }
 
 hotkeys_popup.add_hotkeys(vim_keys)

lib/awful/hotkeys_popup/widget.lua

@@ -601,6 +601,7 @@ function widget.new(args)
             placement = place_func,
             minimum_width = wibox_width,
             minimum_height = wibox_height,
+            screen = s,
         }
 
         local widget_obj = {

lib/awful/mouse/init.lua

@@ -31,12 +31,25 @@ local mouse = {
 mouse.object = {}
 mouse.wibox = {}
 
---- The default snap distance.
+--- The default distance before snapping clients together.
+--
+-- @DOC_screen_client_snap_EXAMPLE@
+--
 -- @tfield integer awful.mouse.snap.default_distance
 -- @tparam[opt=8] integer default_distance
 -- @see awful.mouse.snap
 
+--- The default distance before activating screen edge snap.
+-- @tfield integer awful.mouse.snap.aerosnap_distance
+-- @tparam[opt=16] integer default_distance
+-- @see awful.mouse.snap
+
 --- Enable screen edges snapping.
+--
+--
+--
+--@DOC_awful_placement_aero_snap_EXAMPLE@
+--
 -- @tfield[opt=true] boolean awful.mouse.snap.edge_enabled
 
 --- Enable client to client snapping.
@@ -57,9 +70,9 @@ mouse.wibox = {}
 -- @beautiful beautiful.snap_shape
 -- @tparam function shape A `gears.shape` compatible function
 
---- The gap between snapped contents.
+--- The gap between snapped clients.
 -- @beautiful beautiful.snapper_gap
--- @tparam number (default: 0)
+-- @tparam[opt=0] number snapper_gap
 
 --- Get the client object under the pointer.
 -- @deprecated awful.mouse.client_under_pointer

lib/awful/mouse/snap.lua

@@ -25,7 +25,8 @@ local capi = {
 }
 
 local module = {
-    default_distance = 8
+    default_distance  = 8,
+    aerosnap_distance = 16
 }
 
 local placeholder_w = nil
@@ -258,7 +259,7 @@ resize.add_move_callback(function(c, geo, args)
     -- Screen edge snapping (areosnap)
     if (module.edge_enabled ~= false)
       and args and (args.snap == nil or args.snap) then
-        detect_areasnap(c, 16)
+        detect_areasnap(c, module.aerosnap_distance)
     end
 
     -- Snapping between clients

lib/awful/permissions/init.lua

@@ -542,7 +542,7 @@ end, "mouse_enter")
 -- depending if the client is tiled, floating, maximized and then from its state
 -- (urgent, new, active, normal)
 --
--- @signalhandler awful.ewmh.update_border
+-- @signalhandler awful.permissions.update_border
 -- @usebeautiful beautiful.border_color_marked
 -- @usebeautiful beautiful.border_color_active
 -- @usebeautiful beautiful.border_color_normal

lib/awful/popup.lua

@@ -19,6 +19,7 @@
 -- @author Emmanuel Lepage Vallee
 -- @copyright 2016 Emmanuel Lepage Vallee
 -- @popupmod awful.popup
+-- @supermodule wibox
 ---------------------------------------------------------------------------
 local wibox     = require( "wibox"           )
 local gtable    = require( "gears.table"     )

lib/awful/screen.lua

@@ -234,6 +234,7 @@ end
 -- @tfield integer table.right The padding on the right.
 -- @tfield integer table.top The padding on the top.
 -- @tfield integer table.bottom The padding on the bottom.
+-- @usebeautiful beautiful.maximized_honor_padding Honor the screen padding when maximizing.
 
 function screen.object.get_padding(self)
     local p = data.padding[self] or {}
@@ -503,9 +504,8 @@ function screen.object.get_tiled_clients(s, stacked)
     -- Remove floating clients
     for _, c in pairs(clients) do
         if not c.floating
-            and not c.fullscreen
+            and not c.immobilized_horizontal
-            and not c.maximized_vertical
+            and not c.immobilized_vertical then
-            and not c.maximized_horizontal then
             table.insert(tclients, c)
         end
     end

lib/awful/tag.lua

@@ -349,6 +349,45 @@ function tag.find_fallback(screen, invalids)
     end
 end
 
+--- When all clients are removed from the tag.
+-- @signal cleared
+-- @see clear
+
+--- Remove all tagged clients.
+--
+-- @DOC_sequences_tag_clear_EXAMPLE@
+--
+-- @method clear
+-- @tparam table args The arguments.
+-- @tparam tag args.fallback_tag A fallback tag.
+-- @tparam[opt=false] boolean args.allow_untagged Allow the untagged clients to remain untagged.
+-- @emits cleared After all clients have been untagged.
+-- @emits untagged For each currently tagged clients.
+-- @emitstparam untagged client c The untagged client.
+function tag.object.clear(self, args)
+    args = args or {}
+
+    local clients = self:clients()
+
+    -- Clear
+    self:clients({})
+
+    if #clients > 0 and not args.allow_untagged then
+        local target_scr = get_screen(tag.getproperty(self, "screen"))
+        local fallback_tag = args.fallback_tag or tag.find_fallback(target_scr, {self})
+
+        if not fallback_tag then return end
+
+        for _, c in ipairs(clients) do
+            if #c:tags() == 0 then
+                c:tags({fallback_tag})
+            end
+        end
+    end
+
+    self:emit_signal("cleared")
+end
+
 --- Delete a tag.
 --
 -- To delete the current tag:
@@ -674,6 +713,13 @@ end
 -- See the layout suit documentation for information about how the master width
 -- factor is used.
 --
+-- @DOC_screen_mwfact_EXAMPLE@
+--
+-- When multiple columns are used, the master width remains the same, but
+-- the other columns split the remaining space among them:
+--
+-- @DOC_screen_mwfact2_EXAMPLE@
+--
 -- **Signal:**
 --
 -- * *property::mwfact* (deprecated)
@@ -685,6 +731,7 @@ end
 -- @see column_count
 -- @see master_fill_policy
 -- @see gap
+-- @see awful.tag.incmwfact
 
 function tag.object.set_master_width_factor(t, mwfact)
     if mwfact >= 0 and mwfact <= 1 then
@@ -1049,9 +1096,17 @@ end
 
 --- The gap (spacing, also called `useless_gap`) between clients.
 --
--- This property allow to waste space on the screen in the name of style,
+-- This property allows to waste space on the screen in the name of style,
 -- unicorns and readability.
 --
+-- In this example, the value of `gap` is set to 20:
+--
+-- @DOC_screen_gaps_EXAMPLE@
+--
+-- Compared to setting to the (very high) value of 50:
+--
+-- @DOC_screen_gaps2_EXAMPLE@
+--
 -- **Signal:**
 --
 -- * *property::useless_gap*
@@ -1059,6 +1114,7 @@ end
 -- @property gap
 -- @param number The value has to be greater than zero.
 -- @see gap_single_client
+-- @see awful.tag.incgap
 
 function tag.object.set_gap(t, useless_gap)
     if useless_gap >= 0 then
@@ -1102,12 +1158,26 @@ end
 
 --- Enable gaps for a single client.
 --
+-- If the gaps are used purely for readability when multiple
+-- clients are tiled, then it may make sense to disable it
+-- when there is only a single client (to recover that space).
+-- In that case, set `gap_single_client` to `false`.
+--
+-- Default (with a 20px gap):
+--
+-- @DOC_screen_gap_single_client_true_EXAMPLE@
+--
+-- when set to false:
+--
+-- @DOC_screen_gap_single_client_false_EXAMPLE@
+--
 -- **Signal:**
 --
 -- * *property::gap\_single\_client*
 --
 -- @property gap_single_client
 -- @param boolean Enable gaps for a single client
+-- @see awful.tag.incgap
 
 function tag.object.set_gap_single_client(t, gap_single_client)
     tag.setproperty(t, "gap_single_client", gap_single_client == true)
@@ -1156,18 +1226,33 @@ end
 
 --- Set size fill policy for the master client(s).
 --
+-- Some multi-column layouts can be configured so that the space is
+-- redistributed when there is not enough clients to fill all columns.
+--
 -- ** Possible values**:
 --
 -- * *expand*: Take all the space
--- * *master_width_factor*: Only take the ratio defined by the
+-- * *master\_width\_factor*: Only take the ratio defined by the
 --   `master_width_factor`
 --
+-- This is the default behavior of the `tile.left` layout (*expand*):
+--
+-- @DOC_screen_mfpol2_EXAMPLE@
+--
+-- This is what happends when set to `master_width_factor`:
+--
+-- @DOC_screen_mfpol_EXAMPLE@
+--
+-- The remaining space that would have been used for the second column is
+-- redistributed on both side.
+--
 -- **Signal:**
 --
 -- * *property::master_fill_policy*
 --
 -- @property master_fill_policy
 -- @param string "expand" or "master_width_factor"
+-- @see awful.tag.togglemfpol
 
 function tag.object.get_master_fill_policy(t)
     return tag.getproperty(t, "master_fill_policy")
@@ -1237,6 +1322,7 @@ end
 --
 -- @property master_count
 -- @param integer nmaster Only positive values are accepted
+-- @see awful.tag.incnmaster
 
 function tag.object.set_master_count(t, nmaster)
     if nmaster >= 0 then
@@ -1304,12 +1390,16 @@ end
 
 --- Set the tag icon.
 --
+-- @DOC_wibox_awidget_taglist_icon_EXAMPLE@
+--
 -- **Signal:**
 --
 -- * *property::icon*
 --
 -- @property icon
 -- @tparam path|surface icon The icon
+-- @see awful.widget.taglist
+-- @see gears.surface
 
 -- accessors are implicit.
 
@@ -1344,6 +1434,8 @@ end
 
 --- Set the number of columns.
 --
+-- @DOC_sequences_tag_column_count_EXAMPLE@
+--
 -- **Signal:**
 --
 -- * *property::ncol* (deprecated)
@@ -1351,6 +1443,7 @@ end
 --
 -- @property column_count
 -- @tparam integer ncol Has to be greater than 1
+-- @see awful.tag.incncol
 
 function tag.object.set_column_count(t, ncol)
     if ncol >= 1 then

lib/awful/titlebar.lua

@@ -654,7 +654,7 @@ end
 -- This way, you can e.g. modify the font that is used.
 -- @param c The client for which a titlewidget should be created.
 -- @return The title widget.
--- @staticfct awful.titlebar.widget.titlewidget
+-- @constructorfct awful.titlebar.widget.titlewidget
 function titlebar.widget.titlewidget(c)
     local ret = textbox()
     local function update()
@@ -672,7 +672,7 @@ end
 -- available. This way, you can e.g. disallow resizes.
 -- @param c The client for which an icon widget should be created.
 -- @return The icon widget.
--- @staticfct awful.titlebar.widget.iconwidget
+-- @constructorfct awful.titlebar.widget.iconwidget
 function titlebar.widget.iconwidget(c)
     return clienticon(c)
 end
@@ -690,7 +690,7 @@ end
 -- @param selector A function that selects the image that should be displayed.
 -- @param action Function that is called when the button is clicked.
 -- @return The widget
--- @staticfct awful.titlebar.widget.button
+-- @constructorfct awful.titlebar.widget.button
 function titlebar.widget.button(c, name, selector, action)
     local ret = imagebox()
 
@@ -778,7 +778,7 @@ end
 
 --- Create a new float button for a client.
 -- @param c The client for which the button is wanted.
--- @staticfct awful.titlebar.widget.floatingbutton
+-- @constructorfct awful.titlebar.widget.floatingbutton
 function titlebar.widget.floatingbutton(c)
     local widget = titlebar.widget.button(c, "floating", aclient.object.get_floating, aclient.floating.toggle)
     update_on_signal(c, "property::floating", widget)
@@ -787,7 +787,7 @@ end
 
 --- Create a new maximize button for a client.
 -- @param c The client for which the button is wanted.
--- @staticfct awful.titlebar.widget.maximizedbutton
+-- @constructorfct awful.titlebar.widget.maximizedbutton
 function titlebar.widget.maximizedbutton(c)
     local widget = titlebar.widget.button(c, "maximized", function(cl)
         return cl.maximized
@@ -800,7 +800,7 @@ end
 
 --- Create a new minimize button for a client.
 -- @param c The client for which the button is wanted.
--- @staticfct awful.titlebar.widget.minimizebutton
+-- @constructorfct awful.titlebar.widget.minimizebutton
 function titlebar.widget.minimizebutton(c)
     local widget = titlebar.widget.button(c, "minimize",
                                           function() return "" end,
@@ -811,14 +811,14 @@ end
 
 --- Create a new closing button for a client.
 -- @param c The client for which the button is wanted.
--- @staticfct awful.titlebar.widget.closebutton
+-- @constructorfct awful.titlebar.widget.closebutton
 function titlebar.widget.closebutton(c)
     return titlebar.widget.button(c, "close", function() return "" end, function(cl) cl:kill() end)
 end
 
 --- Create a new ontop button for a client.
 -- @param c The client for which the button is wanted.
--- @staticfct awful.titlebar.widget.ontopbutton
+-- @constructorfct awful.titlebar.widget.ontopbutton
 function titlebar.widget.ontopbutton(c)
     local widget = titlebar.widget.button(c, "ontop",
                                           function(cl) return cl.ontop end,
@@ -829,7 +829,7 @@ end
 
 --- Create a new sticky button for a client.
 -- @param c The client for which the button is wanted.
--- @staticfct awful.titlebar.widget.stickybutton
+-- @constructorfct awful.titlebar.widget.stickybutton
 function titlebar.widget.stickybutton(c)
     local widget = titlebar.widget.button(c, "sticky",
                                           function(cl) return cl.sticky end,

lib/awful/tooltip.lua

@@ -40,6 +40,7 @@
 -- @author Sébastien Gross <seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org>
 -- @copyright 2009 Sébastien Gross
 -- @popupmod awful.tooltip
+-- @supermodule wibox
 -------------------------------------------------------------------------
 
 local timer = require("gears.timer")

lib/awful/util.lua

@@ -385,7 +385,7 @@ function util.linecount(text)
     return gstring.linecount(text)
 end
 
---- Get a sorted table with all integer keys from a table
+--- Get a sorted table with all keys from a table.
 -- @deprecated util.table.keys
 -- @param t the table for which the keys to get
 -- @return A table with keys

lib/awful/wibar.lua

@@ -11,6 +11,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2016 Emmanuel Lepage Vallee
 -- @popupmod awful.wibar
+-- @supermodule awful.popup
 ---------------------------------------------------------------------------
 
 -- Grab environment we need

lib/awful/widget/button.lua

@@ -1,15 +1,12 @@
 ---------------------------------------------------------------------------
 -- A simple button widget.
 --
---    button.buttons = {
+-- @DOC_wibox_awidget_defaults_button_EXAMPLE@
---        awful.button({}, 1, nil, function ()
---            print("Mouse was clicked")
---        end)
---    }
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
 -- @widgetmod awful.widget.button
+-- @supermodule wibox.widget.imagebox
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -18,6 +15,7 @@ local imagebox = require("wibox.widget.imagebox")
 local widget = require("wibox.widget.base")
 local surface = require("gears.surface")
 local cairo = require("lgi").cairo
+local gtable = require("gears.table")
 
 local button = { mt = {} }
 
@@ -25,10 +23,13 @@ local button = { mt = {} }
 -- a real button.
 --
 -- @constructorfct awful.widget.button
--- @param args Widget arguments. "image" is the image to display.
+-- @tparam table args Widget arguments.
+-- @tparam string args.image "image" is the image to display (mandatory).
+-- @tparam table args.buttons The buttons.
 -- @return A textbox widget configured as a button.
 function button.new(args)
-    if not args or not args.image then
+    args = args or {}
+    if not args.image then
         return widget.empty_widget()
     end
 
@@ -47,10 +48,14 @@ function button.new(args)
     end
     w:set_image(args.image)
 
-    w.buttons = {
+    local btns = gtable.clone(args.buttons or {}, false)
+
+    table.insert(btns,
         abutton({}, 1, function () orig_set_image(w, img_press) end,
                        function () orig_set_image(w, img_release) end)
-    }
+    )
+
+    w.buttons = btns
 
     w:connect_signal("mouse::leave", function(self) orig_set_image(self, img_release) end)
 
@@ -61,10 +66,6 @@ function button.mt:__call(...)
     return button.new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(button, button.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/widget/clienticon.lua

@@ -1,7 +1,10 @@
+---------------------------------------------------------------------------
 --- Container showing the icon of a client.
 -- @author Uli Schlachter
 -- @copyright 2017 Uli Schlachter
 -- @widgetmod awful.widget.clienticon
+-- @supermodule wibox.widget.base
+---------------------------------------------------------------------------
 
 local base = require("wibox.widget.base")
 local surface = require("gears.surface")
@@ -123,10 +126,6 @@ client.connect_signal("property::icon", function(c)
     end
 end)
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(clienticon, {
     __call = function(_, ...)
         return new(...)

lib/awful/widget/launcher.lua

@@ -11,6 +11,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
 -- @widgetmod awful.widget.launcher
+-- @supermodule awful.widget.button
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -50,10 +51,6 @@ function launcher.mt:__call(...)
     return launcher.new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(launcher, launcher.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/widget/layoutbox.lua

@@ -6,6 +6,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Julien Danjou
 -- @widgetmod awful.widget.layoutbox
+-- @supermodule wibox.layout.fixed
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable

lib/awful/widget/layoutlist.lua

@@ -21,6 +21,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2010, 2018 Emmanuel Lepage Vallee
 -- @widgetmod awful.widget.layoutlist
+-- @supermodule wibox.widget.base
 ----------------------------------------------------------------------------
 
 local capi     = {screen = screen, tag = tag}
@@ -444,8 +445,4 @@ local function new(_, args)
     return ret
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(module, {__call = new})

lib/awful/widget/only_on_screen.lua

@@ -5,6 +5,7 @@
 -- @author Uli Schlachter
 -- @copyright 2017 Uli Schlachter
 -- @containermod awful.widget.only_on_screen
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local type = type
@@ -129,10 +130,6 @@ capi.screen.connect_signal("property::outputs", function()
     end
 end)
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(only_on_screen, only_on_screen.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/widget/prompt.lua

@@ -7,6 +7,7 @@
 -- @copyright 2009 Julien Danjou
 -- @copyright 2018 Aire-One
 -- @widgetmod awful.widget.prompt
+-- @supermodule wibox.container.background
 ---------------------------------------------------------------------------
 
 --- The prompt foreground color.
@@ -158,10 +159,6 @@ function widgetprompt.mt:__call(...)
     return widgetprompt.new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(widgetprompt, widgetprompt.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/widget/tasklist.lua

@@ -26,9 +26,9 @@
 --
 -- **Customizing the tasklist:**
 --
--- The `tasklist` created by `rc.lua` use the default values for almost
+-- The `tasklist` created by `rc.lua` uses the default values for almost
--- everything. However, it is possible to override each aspects to create a
+-- everything. However, it is possible to override each aspect to create a
--- very different widget. Here's an example that create a tasklist similar to
+-- very different widget. Here's an example that creates a tasklist similar to
 -- the default one, but with an explicit layout and some spacing widgets:
 --
 --@DOC_wibox_awidget_tasklist_rounded_EXAMPLE@
@@ -508,7 +508,7 @@ end
 --   update. See `awful.widget.common.list_update`.
 -- @tparam[opt] table args.layout Container widget for tag widgets. Default
 --   is `wibox.layout.flex.horizontal`.
--- @tparam[opt=awful.tasklist.source.all_clients] function args.source The
+-- @tparam[opt=awful.widget.tasklist.source.all_clients] function args.source The
 --  function used to generate the list of client.
 -- @tparam[opt] table args.widget_template A custom widget to be used for each client
 -- @tparam[opt={}] table args.style The style overrides default theme.
@@ -687,7 +687,7 @@ end
 
 --- Filtering function to include all clients.
 -- @return true
--- @filterfunction awful.tasklist.filter.allscreen
+-- @filterfunction awful.widget.tasklist.filter.allscreen
 function tasklist.filter.allscreen()
     return true
 end
@@ -696,7 +696,7 @@ end
 -- @param c The client.
 -- @param screen The screen we are drawing on.
 -- @return true if c is on screen, false otherwise
--- @filterfunction awful.tasklist.filter.alltags
+-- @filterfunction awful.widget.tasklist.filter.alltags
 function tasklist.filter.alltags(c, screen)
     -- Only print client on the same screen as this widget
     return get_screen(c.screen) == get_screen(screen)
@@ -706,7 +706,7 @@ end
 -- @param c The client.
 -- @param screen The screen we are drawing on.
 -- @return true if c is in a selected tag on screen, false otherwise
--- @filterfunction awful.tasklist.filter.currenttags
+-- @filterfunction awful.widget.tasklist.filter.currenttags
 function tasklist.filter.currenttags(c, screen)
     screen = get_screen(screen)
     -- Only print client on the same screen as this widget
@@ -731,7 +731,7 @@ end
 -- @param c The client.
 -- @param screen The screen we are drawing on.
 -- @return true if c is in a selected tag on screen and is minimized, false otherwise
--- @filterfunction awful.tasklist.filter.minimizedcurrenttags
+-- @filterfunction awful.widget.tasklist.filter.minimizedcurrenttags
 function tasklist.filter.minimizedcurrenttags(c, screen)
     screen = get_screen(screen)
     -- Only print client on the same screen as this widget
@@ -759,7 +759,7 @@ end
 -- @param c The client.
 -- @param screen The screen we are drawing on.
 -- @return true if c is focused on screen, false otherwise
--- @filterfunction awful.tasklist.filter.focused
+-- @filterfunction awful.widget.tasklist.filter.focused
 function tasklist.filter.focused(c, screen)
     -- Only print client on the same screen as this widget
     return get_screen(c.screen) == get_screen(screen) and c.active
@@ -769,7 +769,7 @@ end
 --
 -- This is the default source.
 --
--- @sourcefunction awful.tasklist.source.all_clients
+-- @sourcefunction awful.widget.tasklist.source.all_clients
 function tasklist.source.all_clients()
     return capi.client.get()
 end

lib/awful/widget/watch.lua

@@ -24,6 +24,10 @@
 --
 -- ![Example screenshot](../images/awful_widget_watch.png)
 --
+-- Here is the most basic usage:
+--
+-- @DOC_wibox_awidget_defaults_watch_EXAMPLE@
+--
 -- @author Benjamin Petrenko
 -- @author Yauheni Kirylau
 -- @copyright 2015, 2016 Benjamin Petrenko, Yauheni Kirylau

lib/beautiful/gtk.lua

@@ -70,7 +70,8 @@ function gtk.get_theme_variables()
 
     local result = {}
     local _gtk_status, Gtk = pcall(function()
-        return require('lgi').Gtk
+        local lgi = require('lgi')
+        return lgi.require('Gtk', '3.0')
     end)
     if not _gtk_status or not Gtk then
         gears_debug.print_warning(

lib/gears/color.lua

@@ -341,9 +341,7 @@ end
 -- @return Recolored image.
 -- @staticfct gears.color.recolor_image
 function color.recolor_image(image, new_color)
-    if type(image) == 'string' then
+    image = surface.duplicate_surface(image)
-        image = surface.duplicate_surface(image)
-    end
     local cr = cairo.Context.create(image)
     cr:set_source(color.create_pattern(new_color))
     cr:mask(cairo.Pattern.create_for_surface(image), 0, 0)

lib/gears/object.lua

@@ -46,9 +46,11 @@ function object.add_signal()
 end
 
 --- Connect to a signal.
+--
 --@DOC_text_gears_object_signal_EXAMPLE@
--- @tparam string name The name of the signal
+--
--- @tparam function func The callback to call when the signal is emitted
+-- @tparam string name The name of the signal.
+-- @tparam function func The callback to call when the signal is emitted.
 -- @method connect_signal
 function object:connect_signal(name, func)
     assert(type(func) == "function", "callback must be a function, got: " .. type(func))
@@ -92,10 +94,16 @@ local function make_the_gc_obey(func)
     return func
 end
 
---- Connect to a signal weakly. This allows the callback function to be garbage
+--- Connect to a signal weakly.
--- collected and automatically disconnects the signal when that happens.
+--
--- @tparam string name The name of the signal
+-- This allows the callback function to be garbage collected and
--- @tparam function func The callback to call when the signal is emitted
+-- automatically disconnects the signal when that happens.
+-- **Warning:**
+-- Only use this function if you really, really, really know what you
+-- are doing.
+--
+-- @tparam string name The name of the signal.
+-- @tparam function func The callback to call when the signal is emitted.
 -- @method weak_connect_signal
 function object:weak_connect_signal(name, func)
     assert(type(func) == "function", "callback must be a function, got: " .. type(func))
@@ -104,9 +112,9 @@ function object:weak_connect_signal(name, func)
     sig.weak[func] = make_the_gc_obey(func)
 end
 
---- Disonnect to a signal.
+--- Disonnect from a signal.
--- @tparam string name The name of the signal
+-- @tparam string name The name of the signal.
--- @tparam function func The callback that should be disconnected
+-- @tparam function func The callback that should be disconnected.
 -- @method disconnect_signal
 function object:disconnect_signal(name, func)
     local sig = find_signal(self, name)
@@ -118,8 +126,8 @@ end
 --
 -- @tparam string name The name of the signal
 -- @param ... Extra arguments for the callback functions. Each connected
---   function receives the object as first argument and then any extra arguments
+--   function receives the object as first argument and then any extra
---   that are given to emit_signal()
+--   arguments that are given to emit_signal()
 -- @method emit_signal
 function object:emit_signal(name, ...)
     local sig = find_signal(self, name)

lib/gears/shape.lua

@@ -4,8 +4,9 @@
 -- It add the concept of "shape" to Awesome. A shape can be applied to a
 -- background, a margin, a mask or a drawable shape bounding.
 --
--- The functions exposed by this module always take a context as first
+-- The functions exposed by this module always take a cairo context as first
--- parameter followed by the widget and height and additional parameters.
+-- parameter followed by a width and height. Individual functions may take
+-- additional parameters for their specific implementions.
 --
 -- The functions provided by this module only create a path in the content.
 -- to actually draw the content, use `cr:fill()`, `cr:mask()`, `cr:clip()` or

lib/gears/string.lua

@@ -116,7 +116,7 @@ end
 -- @tparam string sub String to check for.
 -- @staticfct gears.string.startswith
 function gstring.startswith(str, sub)
-    return string.sub(str, 1, string.len(sub)) == sub
+    return str and (string.sub(str, 1, string.len(sub)) == sub) or false
 end
 
 --- Check if a string ends with another string.
@@ -126,7 +126,7 @@ end
 -- @treturn boolean `true` if string ends with specified string
 -- @staticfct gears.string.endswith
 function gstring.endswith(str, sub)
-    return sub == "" or string.sub(str,-string.len(sub)) == sub
+    return str and (sub == "" or string.sub(str,-string.len(sub)) == sub) or false
 end
 
 return gstring

lib/gears/table.lua

@@ -149,7 +149,7 @@ function gtable.find_first_key(t, matcher, ordered)
 end
 
 
---- Get a sorted table with all integer keys from a table.
+--- Get a sorted table with all keys from a table.
 --
 -- @tparam table t The table for which the keys to get.
 -- @treturn table A table with keys.
@@ -165,6 +165,23 @@ function gtable.keys(t)
     return keys
 end
 
+--- Get the number of keys in a table, both integer and string indicies.
+--
+-- This is functionally equivalent, but faster than `#gears.table.keys(t)`.
+--
+-- @DOC_text_gears_table_count_keys_EXAMPLE@
+--
+-- @tparam table t The table for which to count the keys.
+-- @treturn number The number of keys in the table.
+-- @staticfct gears.table.count_keys
+function gtable.count_keys(t)
+    local count = 0
+    for _ in pairs(t) do
+        count = count + 1
+    end
+    return count
+end
+
 --- Filter a table's keys for certain content type.
 --
 -- @tparam table t The table to retrieve the keys for.
@@ -230,14 +247,16 @@ end
 -- `first_index` has to be specified.
 --
 -- @tparam table t The input table.
--- @param value A value from the table.
+-- @param value The start value. Must be an element of the input table `t`.
--- @tparam[opt=1] number step_size How many element forward (or backward) to pick.
+-- @tparam[opt=1] number step_size The amount to increment the index by.
--- @tparam[opt=nil] function filter An optional function. When it returns
+--   When this is negative, the function will cycle through the table backwards.
---  `false`, the element are skipped until a match if found. It takes the value
+-- @tparam[opt=nil] function filter An optional filter function. It receives a
---  as its sole parameter.
+--   value from the table as parameter and should return a boolean. If it
+--   returns `false`, the value is skipped and `cycle_value` tries the next one.
 -- @tparam[opt=1] number start_at Where to start the lookup from.
--- @return The value. If no element match, then `nil` is returned.
+-- @return The next eligible value. If no value matches, `nil` is returned.
--- @treturn number|nil The element (if any) key.
+-- @treturn number|nil If a value is found, this is its index within the input
+--   table.
 -- @staticfct gears.table.cycle_value
 function gtable.cycle_value(t, value, step_size, filter, start_at)
     local k = gtable.hasitem(t, value, true, start_at)
@@ -400,3 +419,5 @@ function gtable.map(f, tbl)
 end
 
 return gtable
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/naughty/constants.lua

@@ -9,9 +9,10 @@
 -- @copyright 2017 Emmanuel Lepage Vallee
 ----------------------------------------------------------------------------
 local beautiful = require("beautiful")
+local gtable = require("gears.table")
 local dpi = beautiful.xresources.apply_dpi
 
-local ret = {}
+local ret, no_clear = {}, {}
 
 ret.config = {
     padding         = dpi(4),
@@ -21,7 +22,7 @@ ret.config = {
     notify_callback = nil,
 }
 
-ret.config.presets = {
+no_clear.presets = {
     low = {
         timeout = 5
     },
@@ -55,15 +56,15 @@ ret.config._urgency = {
 }
 
 ret.config.mapping = {
-    {{urgency = ret.config._urgency.low     }, ret.config.presets.low}, --compat
+    {{urgency = ret.config._urgency.low     }, no_clear.presets.low}, --compat
-    {{urgency = ret.config._urgency.normal  }, ret.config.presets.normal}, --compat
+    {{urgency = ret.config._urgency.normal  }, no_clear.presets.normal}, --compat
-    {{urgency = ret.config._urgency.critical}, ret.config.presets.critical}, --compat
+    {{urgency = ret.config._urgency.critical}, no_clear.presets.critical}, --compat
-    {{urgency = "low"     }, ret.config.presets.low},
+    {{urgency = "low"     }, no_clear.presets.low},
-    {{urgency = "normal"  }, ret.config.presets.normal},
+    {{urgency = "normal"  }, no_clear.presets.normal},
-    {{urgency = "critical"}, ret.config.presets.critical},
+    {{urgency = "critical"}, no_clear.presets.critical},
 }
 
-ret.config.defaults = {
+no_clear.defaults = {
     timeout      = 5,
     text         = "",
     screen       = nil,
@@ -92,4 +93,21 @@ ret.notification_closed_reason = {
 -- Legacy --TODO v5 remove this alias
 ret.notificationClosedReason = ret.notification_closed_reason
 
+-- `no_clear` is used to prevent users from setting the entire table.
+-- If they did and we added a new default value, then it would not be
+-- backward compatible. For safety, we just crush the tables rather than
+-- replace them.
+setmetatable(ret.config, {
+    __index = function(_, key)
+        return no_clear[key]
+    end,
+    __newindex = function(_, key, value)
+        if no_clear[key] then
+            gtable.crush(no_clear[key], value)
+        else
+            rawset(ret.config, key, value)
+        end
+    end
+})
+
 return ret

lib/naughty/dbus.lua

@@ -341,6 +341,8 @@ function notif_methods.Notify(sender, object_path, interface, method, parameters
             args._unique_sender = sender
 
             notification = nnotif(args)
+
+            notification:connect_signal("destroyed", function(_, r) args.destroy(r) end)
         end
 
         invocation:return_value(GLib.Variant("(u)", { notification.id }))

lib/naughty/layout/box.lua

@@ -8,6 +8,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2017 Emmanuel Lepage Vallee
 -- @popupmod naughty.layout.box
+-- @supermodule awful.popup
 ----------------------------------------------------------------------------
 
 local capi       = {screen=screen}

lib/naughty/notification.lua

@@ -503,6 +503,13 @@ function notification:reset_timeout(new_timeout)
     -- timer before the constructor ends.
     if new_timeout and self.timer then
         self.timeout = new_timeout
+    elseif new_timeout and new_timeout ~= self._private.timeout then
+        local previous_timer = self._private.timeout
+        timer.delayed_call(function()
+            if self._private.timeout == previous_timer then
+                self.timeout = new_timeout
+            end
+        end)
     end
 
     if self.timer and not self.timer.started then

lib/ruled/client.lua

@@ -678,7 +678,7 @@ return setmetatable(module, {
     __newindex = function(_, k, v)
         if k == "rules" then
             gdebug.deprecate(
-                "Use ruled.client.append_rules instead awful.rules.rules",
+                "Use ruled.client.append_rules instead of setting awful.rules.rules directly",
                 {deprecated_in=5}
             )
 
@@ -694,7 +694,7 @@ return setmetatable(module, {
                 crules:append_rules("awful.rules", v)
             end
         else
-            rawset(k, v)
+            rawset(module, k, v)
         end
     end,
     __index = function(_, k)

lib/wibox/container/arcchart.lua

@@ -8,6 +8,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2013 Emmanuel Lepage Vallee
 -- @containermod wibox.container.arcchart
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -357,10 +358,6 @@ function arcchart.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(arcchart, arcchart.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/container/background.lua

@@ -6,6 +6,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @containermod wibox.container.background
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local base = require("wibox.widget.base")
@@ -484,10 +485,6 @@ function background.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(background, background.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/container/constraint.lua

@@ -5,6 +5,7 @@
 -- @author Lukáš Hrázký
 -- @copyright 2012 Lukáš Hrázký
 -- @containermod wibox.container.constraint
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -176,10 +177,6 @@ function constraint.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(constraint, constraint.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/container/margin.lua

@@ -5,6 +5,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @containermod wibox.container.margin
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local pairs = pairs
@@ -238,10 +239,6 @@ function margin.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(margin, margin.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/container/mirror.lua

@@ -5,6 +5,7 @@
 -- @author dodo
 -- @copyright 2012 dodo
 -- @containermod wibox.container.mirror
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local type = type
@@ -129,10 +130,6 @@ function mirror.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(mirror, mirror.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/container/place.lua

@@ -5,6 +5,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2016 Emmanuel Lepage Vallee
 -- @containermod wibox.container.place
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -199,14 +200,10 @@ local function new(widget, halign, valign)
     return ret
 end
 
-function place.mt:__call(_, ...)
+function place.mt:__call(...)
-    return new(_, ...)
+    return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(place, place.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/container/radialprogressbar.lua

@@ -8,6 +8,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2013 Emmanuel Lepage Vallee
 -- @containermod wibox.container.radialprogressbar
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -277,14 +278,10 @@ local function new(widget)
     return ret
 end
 
-function radialprogressbar.mt:__call(_, ...)
+function radialprogressbar.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(radialprogressbar, radialprogressbar.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/container/rotate.lua

@@ -5,6 +5,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @containermod wibox.container.rotate
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local error = error
@@ -149,10 +150,6 @@ function rotate.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(rotate, rotate.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/container/scroll.lua

@@ -21,6 +21,7 @@
 -- @author Uli Schlachter (based on ideas from Saleur Geoffrey)
 -- @copyright 2015 Uli Schlachter
 -- @containermod wibox.container.scroll
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local cache = require("gears.cache")
@@ -549,10 +550,6 @@ function scroll.step_functions.waiting_nonlinear_back_and_forth(elapsed, size, v
     return (size - visible_size) * state
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return scroll
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/layout/align.lua

@@ -4,6 +4,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @layoutmod wibox.layout.align
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local table = table
@@ -320,10 +321,6 @@ end
 
 --@DOC_fixed_COMMON@
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return align
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/layout/fixed.lua

@@ -4,6 +4,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @layoutmod wibox.layout.fixed
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local unpack = unpack or table.unpack -- luacheck: globals unpack (compatibility with Lua 5.1)
@@ -381,10 +382,6 @@ end
 
 --@DOC_fixed_COMMON@
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return fixed
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/layout/flex.lua

@@ -4,6 +4,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @layoutmod wibox.layout.flex
+-- @supermodule wibox.layout.fixed
 ---------------------------------------------------------------------------
 
 local base = require("wibox.widget.base")
@@ -15,6 +16,16 @@ local gtable = require("gears.table")
 
 local flex = {}
 
+-- {{{ Override inherited properties we want to hide
+
+--- From `wibox.layout.fixed`.
+-- @property fill_space
+-- @tparam boolean fill_space
+-- @propemits true false
+-- @hidden
+
+-- }}}
+
 --- Add some widgets to the given fixed layout.
 --
 -- @tparam widget ... Widgets that should be added (must at least be one).
@@ -208,10 +219,6 @@ end
 
 --@DOC_fixed_COMMON@
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return flex
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/layout/grid.lua

@@ -14,6 +14,7 @@
 -- @author getzze
 -- @copyright 2017 getzze
 -- @layoutmod wibox.layout.grid
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -692,7 +693,7 @@ end
 -- getting the common property returns the directional property
 -- defined by the `orientation` property
 for _, prop in ipairs(dir_properties) do
-    for _,dir in ipairs{"horizontal_, vertical_"} do
+    for _,dir in ipairs{"horizontal", "vertical"} do
         local dir_prop = dir .. "_" .. prop
         grid["set_"..dir_prop] = function(self, value)
             if self._private[dir_prop] ~= value then
@@ -961,10 +962,6 @@ end
 
 --@DOC_fixed_COMMON@
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(grid, grid.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/layout/manual.lua

@@ -8,6 +8,7 @@
 -- @author Emmanuel Lepage Vallee
 -- @copyright 2016 Emmanuel Lepage Vallee
 -- @layoutmod wibox.layout.manual
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 local gtable = require("gears.table")
 local base = require("wibox.widget.base")
@@ -245,8 +246,4 @@ end
 
 --@DOC_fixed_COMMON@
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(manual_layout, {__call=function(_,...) return new_manual(...) end})

lib/wibox/layout/ratio.lua

@@ -7,6 +7,8 @@
 -- @author Emmanuel Lepage Vallee
 -- @copyright 2016 Emmanuel Lepage Vallee
 -- @layoutmod wibox.layout.ratio
+-- @supermodule wibox.layout.flex
+-- @see 03-declarative-layout.md
 ---------------------------------------------------------------------------
 
 local base  = require("wibox.widget.base" )
@@ -524,10 +526,6 @@ end
 
 --@DOC_fixed_COMMON@
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return ratio
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/layout/stack.lua

@@ -12,6 +12,7 @@
 -- @author Emmanuel Lepage Vallee
 -- @copyright 2016 Emmanuel Lepage Vallee
 -- @layoutmod wibox.layout.stack
+-- @supermodule wibox.layout.fixed
 ---------------------------------------------------------------------------
 
 local base  = require("wibox.widget.base" )
@@ -116,11 +117,11 @@ end
 -- @method raise
 -- @tparam number index the widget index to raise
 function stack:raise(index)
-    if (not index) or self._private.widgets[index] then return end
+    if (not index) or (not self._private.widgets[index]) then return end
 
     local w = self._private.widgets[index]
     table.remove(self._private.widgets, index)
-    table.insert(self._private.widgets, w)
+    table.insert(self._private.widgets, 1, w)
 
     self:emit_signal("widget::layout_changed")
 end
@@ -170,8 +171,12 @@ end
 
 function stack:set_horizontal_offset(value)
     self._private.h_offset = value
-    self:emit_signal("widget::horizontal_offset")
+    self:emit_signal("widget::layout_changed")
-    self:emit_signal("property::top_only", value)
+    self:emit_signal("property::horizontal_offset", value)
+end
+
+function stack:get_horizontal_offset()
+    return self._private.h_offset
 end
 
 function stack:set_vertical_offset(value)
@@ -180,6 +185,10 @@ function stack:set_vertical_offset(value)
     self:emit_signal("property::vertical_offset", value)
 end
 
+function stack:get_vertical_offset()
+    return self._private.v_offset
+end
+
 --- Create a new stack layout.
 --
 -- @constructorfct wibox.layout.stack
@@ -196,15 +205,11 @@ local function new(...)
     return ret
 end
 
-function stack.mt:__call(_, ...)
+function stack.mt:__call(...)
     return new(...)
 end
 
 --@DOC_fixed_COMMON@
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(stack, stack.mt)
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/base.lua

@@ -2,6 +2,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @classmod wibox.widget.base
+-- @supermodule gears.object
 ---------------------------------------------------------------------------
 
 local object = require("gears.object")
@@ -17,6 +18,184 @@ local table = table
 
 local base = {}
 
+-- {{{ Properties available on all widgets
+
+--- Get or set the children elements.
+-- @property children
+-- @tparam table children The children.
+-- @baseclass wibox.widget.base
+
+--- Get all direct and indirect children widgets.
+-- This will scan all containers recursively to find widgets
+-- Warning: This method it prone to stack overflow if there is a loop in the
+-- widgets hierarchy. A hierarchy loop is when a widget, or any of its
+-- children, contain (directly or indirectly) itself.
+-- @property all_children
+-- @tparam table children The children.
+-- @baseclass wibox.widget.base
+
+--- Force a widget height.
+-- @property forced_height
+-- @tparam number|nil height The height (`nil` for automatic)
+-- @baseclass wibox.widget.base
+
+--- Force a widget width.
+-- @property forced_width
+-- @tparam number|nil width The width (`nil` for automatic)
+-- @baseclass wibox.widget.base
+
+--- The widget opacity (transparency).
+-- @property opacity
+-- @tparam[opt=1] number opacity The opacity (between 0 and 1)
+-- @baseclass wibox.widget.base
+
+--- The widget visibility.
+-- @property visible
+-- @param boolean
+-- @baseclass wibox.widget.base
+
+--- The widget buttons.
+--
+-- The table contains a list of `awful.button` objects.
+-- @property buttons
+-- @param table
+-- @see awful.button
+-- @baseclass wibox.widget.base
+
+-- }}}
+
+-- {{{ Signals available on the widgets.
+
+--- When the layout (size) change.
+-- This signal is emitted when the previous results of `:layout()` and `:fit()`
+-- are no longer valid.  Unless this signal is emitted, `:layout()` and `:fit()`
+-- must return the same result when called with the same arguments.
+-- @signal widget::layout_changed
+-- @see widget::redraw_needed
+-- @baseclass wibox.widget.base
+
+--- When the widget content changed.
+-- This signal is emitted when the content of the widget changes. The widget will
+-- be redrawn, it is not re-layouted. Put differently, it is assumed that
+-- `:layout()` and `:fit()` would still return the same results as before.
+-- @signal widget::redraw_needed
+-- @see widget::layout_changed
+-- @baseclass wibox.widget.base
+
+--- When a mouse button is pressed over the widget.
+-- @signal button::press
+-- @tparam table self The current object instance itself.
+-- @tparam number lx The horizontal position relative to the (0,0) position in
+-- the widget.
+-- @tparam number ly The vertical position relative to the (0,0) position in the
+-- widget.
+-- @tparam number button The button number.
+-- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift)
+-- @tparam table find_widgets_result The entry from the result of
+-- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
+-- the widget.
+-- @tparam widget find_widgets_result.widget The widget being displayed.
+-- @tparam wibox.hierarchy find_widgets_result.hierarchy The hierarchy
+-- managing the widget's geometry.
+-- @tparam number find_widgets_result.x An approximation of the X position that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.y An approximation of the Y position that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.width An approximation of the width that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.height An approximation of the height that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.widget_width The exact width of the widget
+-- in its local coordinate system.
+-- @tparam number find_widgets_result.widget_height The exact height of the widget
+-- in its local coordinate system.
+-- @see mouse
+-- @baseclass wibox.widget.base
+
+--- When a mouse button is released over the widget.
+-- @signal button::release
+-- @tparam table self The current object instance itself.
+-- @tparam number lx The horizontal position relative to the (0,0) position in
+-- the widget.
+-- @tparam number ly The vertical position relative to the (0,0) position in the
+-- widget.
+-- @tparam number button The button number.
+-- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift)
+-- @tparam table find_widgets_result The entry from the result of
+-- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
+-- the widget.
+-- @tparam widget find_widgets_result.widget The widget being displayed.
+-- @tparam wibox.hierarchy find_widgets_result.hierarchy The hierarchy
+-- managing the widget's geometry.
+-- @tparam number find_widgets_result.x An approximation of the X position that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.y An approximation of the Y position that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.width An approximation of the width that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.height An approximation of the height that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.widget_width The exact width of the widget
+-- in its local coordinate system.
+-- @tparam number find_widgets_result.widget_height The exact height of the widget
+-- in its local coordinate system.
+-- @see mouse
+-- @baseclass wibox.widget.base
+
+--- When the mouse enter a widget.
+-- @signal mouse::enter
+-- @tparam table self The current object instance itself.
+-- @tparam table find_widgets_result The entry from the result of
+-- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
+-- the widget.
+-- @tparam widget find_widgets_result.widget The widget being displayed.
+-- @tparam wibox.hierarchy find_widgets_result.hierarchy The hierarchy
+-- managing the widget's geometry.
+-- @tparam number find_widgets_result.x An approximation of the X position that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.y An approximation of the Y position that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.width An approximation of the width that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.height An approximation of the height that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.widget_width The exact width of the widget
+-- in its local coordinate system.
+-- @tparam number find_widgets_result.widget_height The exact height of the widget
+-- in its local coordinate system.
+-- @see mouse
+-- @baseclass wibox.widget.base
+
+--- When the mouse leave a widget.
+-- @signal mouse::leave
+-- @tparam table self The current object instance itself.
+-- @tparam table find_widgets_result The entry from the result of
+-- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
+-- the widget.
+-- @tparam widget find_widgets_result.widget The widget being displayed.
+-- @tparam wibox.hierarchy find_widgets_result.hierarchy The hierarchy
+-- managing the widget's geometry.
+-- @tparam number find_widgets_result.x An approximation of the X position that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.y An approximation of the Y position that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.width An approximation of the width that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.height An approximation of the height that
+-- the widget is visible at on the surface.
+-- @tparam number find_widgets_result.widget_width The exact width of the widget
+-- in its local coordinate system.
+-- @tparam number find_widgets_result.widget_height The exact height of the widget
+-- in its local coordinate system.
+-- @see mouse
+-- @baseclass wibox.widget.base
+
+-- }}}
+
 -- {{{ Functions on widgets
 
 -- Functions available on all widgets.
@@ -30,7 +209,8 @@ end, true)
 
 --- Set a widget's visibility.
 -- @tparam boolean b Whether the widget is visible.
--- @method set_visible
+-- @method wibox.widget.base:set_visible
+-- @hidden
 function base.widget:set_visible(b)
     if b ~= self._private.visible then
         self._private.visible = b
@@ -42,6 +222,7 @@ end
 
 --- Add a new `awful.button` to this widget.
 -- @tparam awful.button button The button to add.
+-- @method wibox.widget.base:add_button
 function base.widget:add_button(button)
     if not button then return end
 
@@ -65,7 +246,8 @@ end
 
 --- Is the widget visible?
 -- @treturn boolean
--- @method get_visible
+-- @method wibox.widget.base:get_visible
+-- @hidden
 function base.widget:get_visible()
     return self._private.visible or false
 end
@@ -73,7 +255,8 @@ end
 --- Set a widget's opacity.
 -- @tparam number o The opacity to use (a number from 0 (transparent) to 1
 -- (opaque)).
--- @method set_opacity
+-- @method wibox.widget.base:set_opacity
+-- @hidden
 function base.widget:set_opacity(o)
     if o ~= self._private.opacity then
         self._private.opacity = o
@@ -83,7 +266,8 @@ end
 
 --- Get the widget's opacity.
 -- @treturn number The opacity (between 0 (transparent) and 1 (opaque)).
--- @method get_opacity
+-- @method wibox.widget.base:get_opacity
+-- @hidden
 function base.widget:get_opacity()
     return self._private.opacity
 end
@@ -91,8 +275,9 @@ end
 --- Set the widget's forced width.
 -- @tparam[opt] number width With `nil` the default mechanism of calling the
 --   `:fit` method is used.
--- @see fit_widget
+-- @see wibox.widget.base:fit_widget
--- @method set_forced_width
+-- @method wibox.widget.base:set_forced_width
+-- @hidden
 function base.widget:set_forced_width(width)
     if width ~= self._private.forced_width then
         self._private.forced_width = width
@@ -108,7 +293,8 @@ end
 -- actual size is during a `mouse::enter`, `mouse::leave` or button event.
 -- @treturn[opt] number The forced width (nil if automatic).
 -- @see fit_widget
--- @method get_forced_width
+-- @method wibox.widget.base:get_forced_width
+-- @hidden
 function base.widget:get_forced_width()
     return self._private.forced_width
 end
@@ -116,8 +302,9 @@ end
 --- Set the widget's forced height.
 -- @tparam[opt] number height With `nil` the default mechanism of calling the
 --   `:fit` method is used.
--- @see fit_widget
+-- @see wibox.widget.base:fit_widget
--- @method set_height
+-- @method wibox.widget.base:set_height
+-- @hidden
 function base.widget:set_forced_height(height)
     if height ~= self._private.forced_height then
         self._private.forced_height = height
@@ -132,7 +319,8 @@ end
 -- If there is no forced width/height, then the only way to get the widget's
 -- actual size is during a `mouse::enter`, `mouse::leave` or button event.
 -- @treturn[opt] number The forced height (nil if automatic).
--- @method get_forced_height
+-- @method wibox.widget.base:get_forced_height
+-- @hidden
 function base.widget:get_forced_height()
     return self._private.forced_height
 end
@@ -141,7 +329,8 @@ end
 --
 -- This method should be re-implemented by the relevant widgets.
 -- @treturn table children The children.
--- @method get_children
+-- @method wibox.widget.base:get_children
+-- @hidden
 function base.widget:get_children()
     return {}
 end
@@ -151,7 +340,8 @@ end
 -- The default implementation does nothing, this must be re-implemented by
 -- all layout and container widgets.
 -- @tparam table children A table composed of valid widgets.
--- @method set_children
+-- @method wibox.widget.base:set_children
+-- @hidden
 function base.widget:set_children(children) -- luacheck: no unused
     -- Nothing on purpose
 end
@@ -171,7 +361,8 @@ end
 -- *Warning*: This method it prone to stack overflow if the widget, or any of
 -- its children, contains (directly or indirectly) itself.
 -- @treturn table children The children.
--- @method get_all_children
+-- @method wibox.widget.base:get_all_children
+-- @hidden
 function base.widget:get_all_children()
     local ret = {}
     digg_children(ret, self)
@@ -197,8 +388,10 @@ function base.set_widget_common(self, widget)
 end
 
 --- Emit a signal and ensure all parent widgets in the hierarchies also
--- forward the signal. This is useful to track signals when there is a dynamic
+-- forward the signal.
--- set of containers and layouts wrapping the widget.
+--
+-- This is useful to track signals when there is a dynamic set of containers
+--   and layouts wrapping the widget.
 --
 -- Note that this function has some flaws:
 --
@@ -213,7 +406,7 @@ end
 --
 -- @tparam string signal_name
 -- @param ... Other arguments
--- @method emit_signal_recursive
+-- @method wibox.widget.base:emit_signal_recursive
 function base.widget:emit_signal_recursive(signal_name, ...)
     -- This is a convenience wrapper, the real implementation is in the
     -- hierarchy.
@@ -223,12 +416,14 @@ end
 
 --- Get the index of a widget.
 -- @tparam widget widget The widget to look for.
--- @tparam[opt] boolean recursive Also check sub-widgets?
+-- @tparam[opt] boolean recursive Recursively check accross the sub-widgets
--- @tparam[opt] widget ... Additional widgets to add at the end of the "path"
+--   hierarchy.
--- @treturn number The index.
+-- @tparam[opt] widget ... Additional widgets to add at the end of the
+--   sub-widgets hierarchy "path".
+-- @treturn number The widget index.
 -- @treturn widget The parent widget.
--- @treturn table The path between "self" and "widget".
+-- @treturn table The hierarchy path between "self" and "widget".
--- @method index
+-- @method wibox.widget.base:index
 function base.widget:index(widget, recursive, ...)
     local widgets = self:get_children()
     for idx, w in ipairs(widgets) do
@@ -533,32 +728,34 @@ local function drill(ids, content)
         end
     end
 
-    -- Add all widgets.
+    if widgets and max > 0 then
-    for k = 1, max do
+        -- Add all widgets.
-        -- ipairs cannot be used on sparse tables.
+        for k = 1, max do
-        local v, id2, e = widgets[k], id, nil
+            -- ipairs cannot be used on sparse tables.
-        if v then
+            local v, id2, e = widgets[k], id, nil
-            -- It is another declarative container, parse it.
+            if v then
-            if (not v.is_widget) and (v.widget or v.layout) then
+                -- It is another declarative container, parse it.
-                e, id2 = drill(ids, v)
+                if (not v.is_widget) and (v.widget or v.layout) then
-                widgets[k] = e
+                    e, id2 = drill(ids, v)
-            elseif (not v.is_widget) and is_callable(v) then
+                    widgets[k] = e
-                 widgets[k] = v()
+                elseif (not v.is_widget) and is_callable(v) then
-            end
+                     widgets[k] = v()
-            base.check_widget(widgets[k])
+                end
+                base.check_widget(widgets[k])
 
-            -- Place the widget in the access table.
+                -- Place the widget in the access table.
-            if id2 then
+                if id2 then
-                l  [id2] = e
+                    l  [id2] = e
-                ids[id2] = ids[id2] or {}
+                    ids[id2] = ids[id2] or {}
-                table.insert(ids[id2], e)
+                    table.insert(ids[id2], e)
+                end
             end
         end
-    end
+
-    -- Replace all children (if any) with the new ones.
+        -- Replace all children (if any) with the new ones.
-    if widgets then
         l:set_children(widgets)
     end
+
     return l, id
 end
 
@@ -575,7 +772,8 @@ end
 --
 -- See [The declarative layout system](../documentation/03-declarative-layout.md.html).
 -- @tparam table args A table containing the widget's disposition.
--- @method setup
+-- @method wibox.widget.base:setup
+-- @hidden
 function base.widget:setup(args)
     local f,ids = self.set_widget or self.add or self.set_first,{}
     local w, id = drill(ids, args)

lib/wibox/widget/checkbox.lua

@@ -9,6 +9,7 @@
 -- @author Emmanuel Lepage Valle
 -- @copyright 2010 Emmanuel Lepage Vallee
 -- @widgetmod wibox.widget.checkbox
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local color     = require( "gears.color"       )
@@ -303,10 +304,6 @@ local function new(checked, args)
     return ret
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable({}, { __call = function(_, ...) return new(...) end})
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/graph.lua

@@ -14,6 +14,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Julien Danjou
 -- @widgetmod wibox.widget.graph
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -27,10 +28,21 @@ local beautiful = require("beautiful")
 
 local graph = { mt = {} }
 
+--- Set the graph border_width.
+--
+--@DOC_wibox_widget_graph_border_width_EXAMPLE@
+--
+-- @property border_width
+-- @tparam number border_width
+-- @propemits true false
+-- @see border_color
+
 --- Set the graph border color.
 --
 -- If the value is nil, no border will be drawn.
 --
+--@DOC_wibox_widget_graph_border_color_EXAMPLE@
+--
 -- @property border_color
 -- @tparam gears.color border_color The border color to set.
 -- @propbeautiful
@@ -39,6 +51,8 @@ local graph = { mt = {} }
 
 --- Set the graph foreground color.
 --
+--@DOC_wibox_widget_graph_color_EXAMPLE@
+--
 -- @property color
 -- @tparam color color The graph color.
 -- @usebeautiful beautiful.graph_fg
@@ -47,6 +61,8 @@ local graph = { mt = {} }
 
 --- Set the graph background color.
 --
+--@DOC_wibox_widget_graph_background_color_EXAMPLE@
+--
 -- @property background_color
 -- @tparam gears.color background_color The graph background color.
 -- @usebeautiful beautiful.graph_bg
@@ -55,6 +71,8 @@ local graph = { mt = {} }
 
 --- Set the maximum value the graph should handle.
 --
+-- @DOC_wibox_widget_graph_max_value_EXAMPLE@
+--
 -- If "scale" is also set, the graph never scales up below this value, but it
 -- automatically scales down to make all data fit.
 --
@@ -64,6 +82,8 @@ local graph = { mt = {} }
 
 --- The minimum value.
 --
+-- @DOC_wibox_widget_graph_min_value_EXAMPLE@
+--
 -- Note that the min_value is not supported when used along with the stack
 -- property.
 -- @property min_value
@@ -72,6 +92,8 @@ local graph = { mt = {} }
 
 --- Set the graph to automatically scale its values. Default is false.
 --
+--@DOC_wibox_widget_graph_scale1_EXAMPLE@
+--
 -- @property scale
 -- @tparam boolean scale
 -- @propemits true false
@@ -90,12 +112,16 @@ local graph = { mt = {} }
 --
 -- Note that it isn't supported when used along with stacked graphs.
 --
+--@DOC_wibox_widget_graph_step_spacing_EXAMPLE@
+--
 -- @property step_spacing
 -- @tparam[opt=0] number step_spacing
 -- @propemits true false
 
 --- The step shape.
 --
+--@DOC_wibox_widget_graph_step_shape_EXAMPLE@
+--
 -- @property step_shape
 -- @tparam[opt=rectangle] gears.shape|function step_shape
 -- @propemits true false
@@ -103,6 +129,7 @@ local graph = { mt = {} }
 
 --- Set the graph to draw stacks. Default is false.
 --
+--@DOC_wibox_widget_graph_stacked_EXAMPLE@
 -- @property stack
 -- @tparam boolean stack
 -- @propemits true false
@@ -130,7 +157,7 @@ local graph = { mt = {} }
 local properties = { "width", "height", "border_color", "stack",
                      "stack_colors", "color", "background_color",
                      "max_value", "scale", "min_value", "step_shape",
-                     "step_spacing", "step_width" }
+                     "step_spacing", "step_width", "border_width" }
 
 function graph.draw(_graph, _, cr, width, height)
     local max_value = _graph._private.max_value
@@ -141,8 +168,9 @@ function graph.draw(_graph, _, cr, width, height)
     local step_shape = _graph._private.step_shape
     local step_spacing = _graph._private.step_spacing or 0
     local step_width = _graph._private.step_width or 1
+    local bw = _graph._private.border_width or 1
 
-    cr:set_line_width(1)
+    cr:set_line_width(bw)
 
     -- Draw the background first
     cr:set_source(color(_graph._private.background_color or beautiful.graph_bg or "#000000aa"))
@@ -150,9 +178,10 @@ function graph.draw(_graph, _, cr, width, height)
 
     -- Account for the border width
     cr:save()
+
     if _graph._private.border_color then
-        cr:translate(1, 1)
+        cr:translate(bw, bw)
-        width, height = width - 2, height - 2
+        width, height = width - 2*bw, height - 2*bw
     end
 
     -- Draw a stacked graph
@@ -239,10 +268,10 @@ function graph.draw(_graph, _, cr, width, height)
     -- Draw the border last so that it overlaps already drawn values
     if _graph._private.border_color then
         -- We decremented these by two above
-        width, height = width + 2, height + 2
+        width, height = width + 2*bw, height + 2*bw
 
         -- Draw the border
-        cr:rectangle(0.5, 0.5, width - 1, height - 1)
+        cr:rectangle(bw/2, bw/2, width - bw, height - bw)
         cr:set_source(color(_graph._private.border_color or beautiful.graph_border_color or "#ffffff"))
         cr:stroke()
     end
@@ -277,7 +306,7 @@ function graph:add_value(value, group)
     table.insert(values, value)
 
     local border_width = 0
-    if self._private.border_color then border_width = 2 end
+    if self._private.border_color then border_width = self._private.border_width*2 end
 
     -- Ensure we never have more data than we can draw
     while #values > self._private.width - border_width do
@@ -385,10 +414,6 @@ function graph.mt:__call(...)
     return graph.new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(graph, graph.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/imagebox.lua

@@ -21,6 +21,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @widgetmod wibox.widget.imagebox
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local lgi = require("lgi")
@@ -160,7 +161,8 @@ end
 --
 -- The image can be a file, a cairo image surface, or an rsvg handle object
 -- (see the [image property](#image)).
--- @method imagebox:set_image
+-- @method set_image
+-- @hidden
 -- @tparam image image The image to render.
 -- @treturn boolean `true` on success, `false` if the image cannot be used.
 -- @usage my_imagebox:set_image(beautiful.awesome_icon)
@@ -223,7 +225,8 @@ end
 -- Any other parameters will be passed to the clip shape function.
 --
 -- @tparam function|gears.shape clip_shape A `gears_shape` compatible shape function.
--- @method imagebox:set_clip_shape
+-- @method set_clip_shape
+-- @hidden
 -- @see gears.shape
 -- @see clip_shape
 function imagebox:set_clip_shape(clip_shape, ...)
@@ -242,7 +245,8 @@ end
 --- Should the image be resized to fit into the available space?
 -- @tparam boolean allowed If `false`, the image will be clipped, else it will
 --   be resized to fit into the available space.
--- @method imagebox:set_resize
+-- @method set_resize
+-- @hidden
 function imagebox:set_resize(allowed)
     self._private.resize_forbidden = not allowed
     self:emit_signal("widget::redraw_needed")
@@ -290,10 +294,6 @@ function imagebox.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(imagebox, imagebox.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/piechart.lua

@@ -8,6 +8,7 @@
 -- @author Emmanuel Lepage Valle
 -- @copyright 2012 Emmanuel Lepage Vallee
 -- @widgetmod wibox.widget.piechart
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local color     = require( "gears.color"       )
@@ -260,9 +261,5 @@ local function new(data_list)
     return ret
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(module, { __call = function(_, ...) return new(...) end })
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/progressbar.lua

@@ -18,6 +18,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Julien Danjou
 -- @widgetmod wibox.widget.progressbar
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -520,10 +521,6 @@ function progressbar.mt:__call(...)
     return progressbar.new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(progressbar, progressbar.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/separator.lua

@@ -20,6 +20,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2014, 2017 Emmanuel Lepage Vallee
 -- @widgetmod wibox.widget.separator
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 local beautiful = require( "beautiful"         )
 local base      = require( "wibox.widget.base" )
@@ -215,9 +216,5 @@ local function new(args)
     return ret
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(separator, { __call = function(_, ...) return new(...) end })
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/slider.lua

@@ -7,6 +7,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2015 Grigory Mishchenko, 2016 Emmanuel Lepage Vallee
 -- @widgetmod wibox.widget.slider
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -534,14 +535,10 @@ local function new(args)
     return ret
 end
 
-function slider.mt:__call(_, ...)
+function slider.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(slider, slider.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/systray.lua

@@ -2,6 +2,7 @@
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @widgetmod wibox.widget.systray
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local wbase = require("wibox.widget.base")
@@ -224,10 +225,6 @@ function systray.mt:__call(...)
     return instance
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(systray, systray.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/wibox/widget/textbox.lua

@@ -1,10 +1,12 @@
 ---------------------------------------------------------------------------
 --
 --@DOC_wibox_widget_defaults_textbox_EXAMPLE@
+--
 -- @author Uli Schlachter
 -- @author dodo
 -- @copyright 2010, 2011 Uli Schlachter, dodo
 -- @widgetmod wibox.widget.textbox
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local base = require("wibox.widget.base")
@@ -188,7 +190,7 @@ end
 function textbox:set_markup(text)
     local success, message = self:set_markup_silently(text)
     if not success then
-        gdebug.print_error(message)
+        gdebug.print_error(debug.traceback("Error parsing markup: "..message.."\nFailed with string: '"..text.."'"))
     end
 end
 

lib/wibox/widget/textclock.lua

@@ -1,9 +1,46 @@
 ---------------------------------------------------------------------------
 --- Text clock widget.
 --
+-- The `wibox.widget.textclock` widget is part of the Awesome WM's widget
+-- system (see @{03-declarative-layout.md}).
+--
+-- This widget displays a text clock formatted by the
+-- [GLib Date Time format](https://developer.gnome.org/glib/stable/glib-GDateTime.html#g-date-time-format)
+-- and [GTimeZone](https://developer.gnome.org/glib/stable/glib-GTimeZone.html#g-time-zone-new).
+--
+-- The `wibox.widget.textclock` inherits from `wibox.widget.textbox`. It means
+-- that, once created, the user will receive a derivated instance of
+-- `wibox.widget.textbox` associated with a private `gears.timer` to manage
+-- timed updates of the displayed clock.
+--
+-- Use a `wibox.widget.textclock`
+-- ---
+--
+-- @DOC_wibox_widget_defaults_textclock_EXAMPLE@
+--
+-- Alternatively, you can declare the `textclock` widget using the
+-- declarative pattern (Both codes are strictly equivalent):
+--
+-- @DOC_wibox_widget_declarative-pattern_textclock_EXAMPLE@
+--
+-- The GLib DateTime format
+-- ---
+--
+-- The time displayed by the textclock widget can be formated by the GLib
+-- DateTime format.
+--
+-- Here is a short list with commonly used format specifiers (extracted from
+-- the Glib API references):
+--
+--@DOC_glib_timedate_format_COMMON@
+--
+-- You can read more on the GLib DateTime format in the
+-- [GLib documentation](https://developer.gnome.org/glib/stable/glib-GDateTime.html#g-date-time-format).
+--
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Julien Danjou
 -- @widgetmod wibox.widget.textclock
+-- @supermodule wibox.widget.textbox
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -126,10 +163,6 @@ function textclock.mt:__call(...)
     return new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(textclock, textclock.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

luaa.c

@@ -77,7 +77,7 @@
 
 #include <xcb/xcb_atom.h>
 #include <xcb/xcb_aux.h>
-#include "xkb_utf32_to_keysym.c"
+#include "xkb_utf32_to_keysym_compat.c"
 
 #include <unistd.h> /* for gethostname() */
 
@@ -489,7 +489,7 @@ luaA_get_key_name(lua_State *L)
         keysym = keysyms[0];
     }
     else if ((ucs = one_utf8_to_utf32(input, length)) > 0) //syntax #2
-        keysym = xkb_utf32_to_keysym(ucs);
+        keysym = xkb_utf32_to_keysym_compat(ucs);
     else //syntax #3
         keysym = xkb_keysym_from_name(input, XKB_KEYSYM_NO_FLAGS);
 

manpages/awesome-client.1.de.txt

@@ -28,18 +28,18 @@ Das Modul 'awful.remote' muss geladen sein, um diesen Befehl zu benutzen.
 BEISPIELE
 ---------
 ....
-$ awesome-client 'return 1+1, "Hello, world"\
+$ awesome-client 'return 1+1, "Hello, world"'
    double 2
    string "Hello, world"
 
 # Das folgende Beispiel erzeugt keine Ausgabe auf der Kommandozeile,
 # sondern zeigt eine Benachrichtigung an.
 $ awesome-client '
-> naughty = require("naughty")
+  naughty = require("naughty")
-> naughty.notify({
+  naughty.notify({
-> title="CLI-Benachrichtigung",
+  title="CLI-Benachrichtigung",
-> text="Dies ist eine Benachrichtigung von der Kommandozeile!"})
+  text="Dies ist eine Benachrichtigung von der Kommandozeile!"})
-> '
+'
 
 # Starte eine lesen-ausführen-ausgeben-Schleife (REPL).
 # In diesem Modus wird jede Zeile zu awesome geschickt; auf die selbe Art

manpages/awesome-client.1.es.txt

@@ -31,18 +31,18 @@ funcione.
 EXAMPLES
 -------
 ....
-$ awesome-client 'return 1+1, "Hello, world"\
+$ awesome-client 'return 1+1, "Hello, world"'
    double 2
    string "Hello, world"
 
 # The following does not return anything on the command line,
 # but will show a notification.
 $ awesome-client '
-> naughty = require("naughty")
+  naughty = require("naughty")
-> naughty.notify({
+  naughty.notify({
-> title="CLI Notification",
+  title="CLI Notification",
-> text="This is a notification sent from the command line!"})
+  text="This is a notification sent from the command line!"})
-> '
+'
 
 # Entering read-eval-print-loop mode
 # This mode will send every line to awesome, exactly the same as passing

manpages/awesome-client.1.fr.txt

@@ -28,18 +28,18 @@ Le module 'awful.remote' doit être chargé pour que cette commande fonctionne.
 EXAMPLES
 -------
 ....
-$ awesome-client 'return 1+1, "Hello, world"\
+$ awesome-client 'return 1+1, "Hello, world"'
    double 2
    string "Hello, world"
 
 # The following does not return anything on the command line,
 # but will show a notification.
 $ awesome-client '
-> naughty = require("naughty")
+  naughty = require("naughty")
-> naughty.notify({
+  naughty.notify({
-> title="CLI Notification",
+  title="CLI Notification",
-> text="This is a notification sent from the command line!"})
+  text="This is a notification sent from the command line!"})
-> '
+'
 
 # Entering read-eval-print-loop mode
 # This mode will send every line to awesome, exactly the same as passing

manpages/awesome-client.1.it.txt

@@ -31,18 +31,18 @@ comando.
 EXAMPLES
 -------
 ....
-$ awesome-client 'return 1+1, "Hello, world"\
+$ awesome-client 'return 1+1, "Hello, world"'
    double 2
    string "Hello, world"
 
 # The following does not return anything on the command line,
 # but will show a notification.
 $ awesome-client '
-> naughty = require("naughty")
+  naughty = require("naughty")
-> naughty.notify({
+  naughty.notify({
-> title="CLI Notification",
+  title="CLI Notification",
-> text="This is a notification sent from the command line!"})
+  text="This is a notification sent from the command line!"})
-> '
+'
 
 # Entering read-eval-print-loop mode
 # This mode will send every line to awesome, exactly the same as passing

manpages/awesome-client.1.ru.txt

@@ -30,18 +30,18 @@ awesome через D-Bus. Если установлен «rlwrap», то он б
 ПРИМЕРЫ
 -------
 ....
-$ awesome-client 'return 1+1, "Hello, world"\
+$ awesome-client 'return 1+1, "Hello, world"'
    double 2
    string "Hello, world"
 
 # Следующий пример не возвращает ничего в командную строку,
 # но показывает уведомление.
 $ awesome-client '
-> naughty = require("naughty")
+  naughty = require("naughty")
-> naughty.notify({
+  naughty.notify({
-> title="CLI Notification",
+  title="CLI Notification",
-> text="Это уведомление было отправлено из командной строки!"})
+  text="Это уведомление было отправлено из командной строки!"})
-> '
+'
 
 # Интерактивный режим (REPL)
 # В данном режиме каждая строка введенная пользователем

manpages/awesome-client.1.txt

@@ -29,18 +29,18 @@ The 'awful.remote' module has to be loaded if you want this command to work.
 EXAMPLES
 -------
 ....
-$ awesome-client 'return 1+1, "Hello, world"\
+$ awesome-client 'return 1+1, "Hello, world"'
    double 2
    string "Hello, world"
 
 # The following does not return anything on the command line,
 # but will show a notification.
 $ awesome-client '
-> naughty = require("naughty")
+  naughty = require("naughty")
-> naughty.notify({
+  naughty.notify({
-> title="CLI Notification",
+  title="CLI Notification",
-> text="This is a notification sent from the command line!"})
+  text="This is a notification sent from the command line!"})
-> '
+'
 
 # Entering read-eval-print-loop mode
 # This mode will send every line to awesome, exactly the same as passing

objects/client.c

@@ -667,6 +667,8 @@ lua_class_t client_class;
  * cause several other changes to the state in order to ensure that
  * a client's position and its screen are consistent.
  *
+ * @DOC_sequences_client_screen_EXAMPLE@
+ *
  * @property screen
  * @tparam screen screen
  * @propemits false false
@@ -714,18 +716,79 @@ lua_class_t client_class;
  * @property border_width
  * @tparam integer border_width
  * @propemits false false
+ * @usebeautiful beautiful.border_width_active
+ * @usebeautiful beautiful.border_width_normal
+ * @usebeautiful beautiful.border_width_new
+ * @usebeautiful beautiful.border_width_urgent
+ * @usebeautiful beautiful.border_width_floating
+ * @usebeautiful beautiful.border_width_floating_active
+ * @usebeautiful beautiful.border_width_floating_normal
+ * @usebeautiful beautiful.border_width_floating_new
+ * @usebeautiful beautiful.border_width_floating_urgent
+ * @usebeautiful beautiful.border_width_maximized
+ * @usebeautiful beautiful.border_width_maximized_active
+ * @usebeautiful beautiful.border_width_maximized_normal
+ * @usebeautiful beautiful.border_width_maximized_new
+ * @usebeautiful beautiful.border_width_maximized_urgent
+ * @usebeautiful beautiful.border_width_fullscreen
+ * @usebeautiful beautiful.border_width_fullscreen_active
+ * @usebeautiful beautiful.border_width_fullscreen_normal
+ * @usebeautiful beautiful.border_width_fullscreen_new
+ * @usebeautiful beautiful.border_width_fullscreen_urgent
+ * @usebeautiful beautiful.fullscreen_hide_border Hide the border on fullscreen clients.
+ * @usebeautiful beautiful.maximized_hide_border Hide the border on maximized clients.
  * @see request::border
+ * @see awful.permissions.update_border
+ * @see border_color
  */
 
 /**
  * The client border color.
  *
+ * @DOC_awful_client_border_width_EXAMPLE@
+ *
+ * Note that setting this directly will override and disable all related theme
+ * variables.
+ *
  * @property border_color
  * @tparam color border_color Any string, gradients and patterns will be converted to a
  *  cairo pattern.
  * @propemits false false
+ * @usebeautiful beautiful.border_color_marked The fallback color when the
+ *  client is marked.
+ * @usebeautiful beautiful.border_color_active The fallback color when the
+ *  client is active (focused).
+ * @usebeautiful beautiful.border_color_normal The fallback color when the
+ *  client isn't active/floating/new/urgent/maximized/floating/fullscreen.
+ * @usebeautiful beautiful.border_color_new The fallback color when the
+ *  client is new.
+ * @usebeautiful beautiful.border_color_urgent The fallback color when the
+ *  client is urgent.
+ * @usebeautiful beautiful.border_color_floating The fallback color when the
+ *  client is floating and the other colors are not set.
+ * @usebeautiful beautiful.border_color_floating_active The color when the
+ *  client is floating and is active (focused).
+ * @usebeautiful beautiful.border_color_floating_normal The color when the
+ *  client is floating and not new/urgent/active.
+ * @usebeautiful beautiful.border_color_floating_new
+ * @usebeautiful beautiful.border_color_floating_urgent The color when the
+ *  client is floating and urgent.
+ * @usebeautiful beautiful.border_color_maximized
+ * @usebeautiful beautiful.border_color_maximized_active
+ * @usebeautiful beautiful.border_color_maximized_normal
+ * @usebeautiful beautiful.border_color_maximized_new
+ * @usebeautiful beautiful.border_color_maximized_urgent The color when the
+ *  client is urbent and maximized.
+ * @usebeautiful beautiful.border_color_fullscreen
+ * @usebeautiful beautiful.border_color_fullscreen_active
+ * @usebeautiful beautiful.border_color_fullscreen_normal
+ * @usebeautiful beautiful.border_color_fullscreen_new
+ * @usebeautiful beautiful.border_color_fullscreen_urgent The color when the
+ *  client is fullscreen and urgent.
  * @see request::border
+ * @see awful.permissions.update_border
  * @see gears.color
+ * @see border_width
  */
 
 /**
@@ -735,6 +798,22 @@ lua_class_t client_class;
  * @tparam boolean urgent
  * @propemits false false
  * @see request::border
+ * @usebeautiful beautiful.border_color_urgent The fallback color when the
+ *  client is urgent.
+ * @usebeautiful beautiful.border_color_floating_urgent The color when the
+ *  client is floating and urgent.
+ * @usebeautiful beautiful.border_color_maximized_urgent The color when the
+ *  client is urbent and maximized.
+ * @usebeautiful beautiful.border_color_fullscreen_urgent The color when the
+ *  client is fullscreen and urgent.
+ * @usebeautiful beautiful.border_width_urgent The fallback border width when
+ *  the client is urgent.
+ * @usebeautiful beautiful.border_width_floating_urgent The border width when
+ *  the client is floating and urgent.
+ * @usebeautiful beautiful.border_width_maximized_urgent The border width when
+ *  the client is maximized and urgent.
+ * @usebeautiful beautiful.border_width_fullscreen_urgent The border width when
+ *  the client is fullscreen and urgent.
  */
 
 /**
@@ -815,6 +894,12 @@ lua_class_t client_class;
  * @propemits false false
  * @request client geometry fullscreen granted When the client must be resized
  *  because it became (or stop being) fullscreen.
+ * @see maximized_horizontal
+ * @see maximized_vertical
+ * @see immobilized_horizontal
+ * @see immobilized_vertical
+ * @see maximized
+
  */
 
 /**
@@ -828,6 +913,11 @@ lua_class_t client_class;
  * @request client geometry maximized granted When the client must be resized
  *  because it became (or stop being) maximized.
  * @see request::border
+ * @see maximized_horizontal
+ * @see maximized_vertical
+ * @see fullscreen
+ * @see immobilized_horizontal
+ * @see immobilized_vertical
  */
 
 /**
@@ -840,6 +930,11 @@ lua_class_t client_class;
  * @propemits false false
  * @request client geometry maximized_horizontal granted When the client must be resized
  *  because it became (or stop being) maximized horizontally.
+ * @see maximized_vertical
+ * @see fullscreen
+ * @see immobilized_horizontal
+ * @see immobilized_vertical
+ * @see maximized
  */
 
 /**
@@ -852,6 +947,11 @@ lua_class_t client_class;
  * @propemits false false
  * @request client geometry maximized_vertical granted When the client must be resized
  *  because it became (or stop being) maximized vertically.
+ * @see maximized_horizontal
+ * @see fullscreen
+ * @see immobilized_horizontal
+ * @see immobilized_vertical
+ * @see maximized
  */
 
 /**
@@ -994,6 +1094,8 @@ lua_class_t client_class;
  * per screens rather than globally like some other
  * implementations.
  *
+ * @DOC_sequences_client_sticky_EXAMPLE@
+ *
  * @property sticky
  * @tparam boolean sticky
  * @propemits false false
@@ -1224,6 +1326,13 @@ lua_class_t client_class;
  *
  * This corresponds to EWMH's `_NET_WM_STRUT` and `_NET_WM_STRUT_PARTIAL`.
  *
+ * In the example below, 2 object affect the workarea (using their struts):
+ *
+ * * The top wibar add a `top=24`
+ * * The bottom-left client add `bottom=100, left=100`
+ *
+ * @DOC_screen_struts_EXAMPLE@
+ *
  * @tparam table struts A table with new strut values, or none.
  * @treturn table A table with strut values.
  * @method struts
@@ -3380,7 +3489,7 @@ HANDLE_TITLEBAR(left, CLIENT_TITLEBAR_LEFT)
  * @tparam integer geo.x The horizontal position.
  * @tparam integer geo.y The vertical position.
  * @tparam integer geo.width The width.
- * @tparam integer geo.width The height.
+ * @tparam integer geo.height The height.
  * @treturn table A table with client geometry and coordinates.
  * @method geometry
  * @see struts
@@ -3582,7 +3691,7 @@ luaA_client_set_skip_taskbar(lua_State *L, client_t *c)
 static int
 luaA_client_get_name(lua_State *L, client_t *c)
 {
-    lua_pushstring(L, c->name ? c->name : c->alt_name);
+    lua_pushstring(L, NONULL(c->name ? c->name : c->alt_name));
     return 1;
 }
 

objects/tag.c

@@ -473,8 +473,10 @@ luaA_tag_clients(lua_State *L)
     if(lua_gettop(L) == 2)
     {
         luaA_checktable(L, 2);
-        foreach(c, tag->clients)
+        for(int j = 0; j < clients->len; j++)
         {
+            client_t *c = clients->tab[j];
+
             /* Only untag if we aren't going to add this tag again */
             bool found = false;
             lua_pushnil(L);
@@ -483,7 +485,7 @@ luaA_tag_clients(lua_State *L)
                 client_t *tc = luaA_checkudata(L, -1, &client_class);
                 /* Pop the value from lua_next */
                 lua_pop(L, 1);
-                if (tc != *c)
+                if (tc != c)
                     continue;
 
                 /* Pop the key from lua_next */
@@ -491,8 +493,10 @@ luaA_tag_clients(lua_State *L)
                 found = true;
                 break;
             }
-            if(!found)
+            if(!found) {
-                untag_client(*c, tag);
+                untag_client(c, tag);
+                j--;
+            }
         }
         lua_pushnil(L);
         while(lua_next(L, 2))

options.c

@@ -27,6 +27,7 @@
 #include <stdlib.h>
 #include <sys/stat.h>
 #include <getopt.h>
+#include <basedir_fs.h>
 
 #define KEY_VALUE_BUF_MAX 64
 #define READ_BUF_MAX 127
@@ -71,7 +72,7 @@ push_arg(string_array_t *args, char *value, size_t *len)
  * Support both shebang and modeline modes.
  */
 bool
-options_init_config(char *execpath, char *configpath, int *init_flags, string_array_t *paths)
+options_init_config(xdgHandle *xdg, char *execpath, char *configpath, int *init_flags, string_array_t *paths)
 {
     /* The different state the parser can have. */
     enum {
@@ -105,7 +106,27 @@ options_init_config(char *execpath, char *configpath, int *init_flags, string_ar
     string_array_init(&argv);
     string_array_append(&argv, a_strdup(execpath));
 
-    FILE *fp = fopen(configpath, "r");
+    FILE *fp = NULL;
+
+    /* It is too early to know which config works. So we assume
+     * the first one found is the one to use for the modeline. This
+     * may or may not end up being the config that works. However since
+     * knowing if the config works requires to load it, and loading must
+     * be done only after the modeline is parsed, this is the best we can
+     * do
+     */
+    if (!configpath) {
+        const char *xdg_confpath = xdgConfigFind("awesome/rc.lua", xdg);
+
+        /* xdg_confpath is "string1\0string2\0string3\0\0" */
+        if (xdg_confpath && *xdg_confpath)
+            fp = fopen(xdg_confpath, "r");
+        else
+            fp = fopen(AWESOME_DEFAULT_CONF, "r");
+
+        p_delete(&xdg_confpath);
+    } else
+        fp = fopen(configpath, "r");
 
     /* Share the error codepath with parsing errors */
     if (!fp)
@@ -402,7 +423,7 @@ options_check_args(int argc, char **argv, int *init_flags, string_array_t *paths
     char *confpath = NULL;
     int opt;
 
-    while((opt = getopt_long(argc, argv, "vhkc:arml:",
+    while((opt = getopt_long(argc, argv, "vhfkc:arms:l:",
                              long_options, NULL)) != -1) {
         switch(opt)
         {

options.h

@@ -35,5 +35,5 @@ typedef enum {
 } awesome_init_config_t;
 
 char *options_detect_shebang(int argc, char **argv);
-bool options_init_config(char *execpath, char *configpath, int *init_flags, string_array_t *paths);
+bool options_init_config(xdgHandle *xdg, char *execpath, char *configpath, int *init_flags, string_array_t *paths);
 char *options_check_args(int argc, char **argv, int *init_flags, string_array_t *paths);

spec/gears/string_spec.lua

@@ -34,12 +34,14 @@ describe("gears.string", function()
         assert.is_true(gstring.startswith("something", ""))
         assert.is_true(gstring.startswith("something", "some"))
         assert.is_false(gstring.startswith("something", "none"))
+        assert.is_false(gstring.startswith(nil, "anything"))
     end)
 
     describe("endswith", function()
         assert.is_true(gstring.endswith("something", ""))
         assert.is_true(gstring.endswith("something", "thing"))
         assert.is_false(gstring.endswith("something", "that"))
+        assert.is_false(gstring.endswith(nil, "anything"))
     end)
 
     describe("split", function()

spec/gears/table_spec.lua

@@ -2,6 +2,39 @@
 local gtable = require("gears.table")
 
 describe("gears.table", function()
+    it("table.keys", function()
+        local t = { 1, a = 2, 3 }
+        assert.is.same(gtable.keys(t), { 1, 2, "a" })
+    end)
+
+    describe("gears.table.count_keys", function()
+        it("counts keys in an empty table", function()
+            local t = {}
+            assert.is.same(gtable.count_keys(t), 0)
+        end)
+
+        it("counts keys in a sparse array", function()
+            local t = { 1, nil, 3 }
+            assert.is.same(gtable.count_keys(t), 2)
+        end)
+
+        it("counts keys in a regular array", function()
+            local t = { 1, 2, 3 }
+            assert.is.same(gtable.count_keys(t), 3)
+        end)
+
+        it("counts keys in a hash table", function()
+            local t = { a = 1, b = "2", c = true }
+            assert.is.same(gtable.count_keys(t), 3)
+        end)
+
+        it("counts keys in a mixed table", function()
+            local t = { 1, a = 2, nil, 4 }
+            assert.is.same(gtable.count_keys(t), 3)
+        end)
+
+    end)
+
     it("table.keys_filter", function()
         local t = { "a", 1, function() end, false}
         assert.is.same(gtable.keys_filter(t, "number", "function"), { 2, 3 })
@@ -99,3 +132,5 @@ describe("gears.table", function()
         end)
     end)
 end)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

spec/wibox/container/margin_spec.lua

@@ -3,13 +3,60 @@
 -- @copyright 2017 Uli Schlachter
 ---------------------------------------------------------------------------
 
+local base = require('wibox.widget.base')
 local margin = require("wibox.container.margin")
+local imagebox = require("wibox.widget.imagebox")
 local utils = require("wibox.test_utils")
 
 describe("wibox.container.margin", function()
     it("common interfaces", function()
         utils.test_container(margin())
     end)
+
+    describe("composite widgets", function()
+        it("can be wrapped with child", function()
+            local widget_name = "test_widget"
+            local new = function()
+                local ret = base.make_widget_declarative {
+                    {
+                        id = "img",
+                        widget = imagebox,
+                    },
+                    widget = margin,
+                }
+
+                ret.widget_name = widget_name
+
+                return ret
+            end
+
+            local widget = base.make_widget_declarative {
+                widget = new,
+            }
+
+            assert.is.equal(
+                widget_name,
+                widget.widget_name,
+                "Widget name doesn't match"
+            )
+            local children = widget:get_children()
+            assert.is_not.Nil(children, "Widget doesn't have children")
+            assert.is.equal(
+                1,
+                #children,
+                "Widget should have exactly one child"
+            )
+            assert.is.True(
+                children[1].is_widget,
+                "Child widget should be a valid widget"
+            )
+            assert.is.equal(
+                widget.img,
+                children[1],
+                "Child widget should match the id accessor"
+            )
+        end)
+    end)
 end)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

spec/wibox/container/place_spec.lua

@@ -5,11 +5,21 @@
 
 local place = require("wibox.container.place")
 local utils = require("wibox.test_utils")
+local base = require("wibox.widget.base")
 
 describe("wibox.container.place", function()
     it("common interfaces", function()
         utils.test_container(place())
     end)
+
+    describe("constructor", function()
+        it("applies arguments", function()
+            local inner = base.empty_widget()
+            local widget = place(inner)
+
+            assert.is.equal(widget.widget, inner)
+        end)
+    end)
 end)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

spec/wibox/container/radialprogressbar_spec.lua

@@ -5,11 +5,21 @@
 
 local radialprogressbar = require("wibox.container.radialprogressbar")
 local utils = require("wibox.test_utils")
+local base = require("wibox.widget.base")
 
 describe("wibox.container.radialprogressbar", function()
     it("common interfaces", function()
         utils.test_container(radialprogressbar())
     end)
+
+    describe("constructor", function()
+        it("applies arguments", function()
+            local inner = base.empty_widget()
+            local widget = radialprogressbar(inner)
+
+            assert.is.same(widget:get_children(), { inner })
+        end)
+    end)
 end)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

spec/wibox/layout/stack_spec.lua

@@ -0,0 +1,143 @@
+---------------------------------------------------------------------------
+-- @author Lucas Schwiderski
+-- @copyright 2021 Lucas Schwiderski
+---------------------------------------------------------------------------
+
+local stack = require("wibox.layout.stack")
+local base = require("wibox.widget.base")
+local utils = require("wibox.test_utils")
+local p = require("wibox.widget.base").place_widget_at
+
+describe("wibox.layout.fixed", function()
+    local layout
+    before_each(function()
+        layout = stack()
+    end)
+
+    it("empty layout fit", function()
+        assert.widget_fit(layout, { 10, 10 }, { 0, 0 })
+    end)
+
+    it("empty layout layout", function()
+        assert.widget_layout(layout, { 0, 0 }, {})
+    end)
+
+    it("empty add", function()
+        assert.has_error(function()
+            layout:add()
+        end)
+    end)
+
+    describe("with widgets", function()
+        local first, second, third
+
+        before_each(function()
+            first = utils.widget_stub(10, 10)
+            second = utils.widget_stub(15, 15)
+            third = utils.widget_stub(10, 10)
+
+            layout:add(first, second, third)
+        end)
+
+        describe("with enough space", function()
+            it("fit", function()
+                assert.widget_fit(layout, { 100, 100 }, { 15, 15 })
+            end)
+
+            it("layout", function()
+                assert.widget_layout(layout, { 100, 100 }, {
+                    p(first,  0, 0, 100, 100),
+                    p(second, 0, 0, 100, 100),
+                    p(third,  0, 0, 100, 100),
+                })
+            end)
+        end)
+
+        describe("without enough height", function()
+            it("fit", function()
+                assert.widget_fit(layout, { 5, 100 }, { 5, 15 })
+            end)
+
+            it("layout", function()
+                assert.widget_layout(layout, { 5, 100 }, {
+                    p(first,  0, 0, 5, 100),
+                    p(second, 0, 0, 5, 100),
+                    p(third,  0, 0, 5, 100),
+                })
+            end)
+        end)
+
+        describe("without enough width", function()
+            it("fit", function()
+                assert.widget_fit(layout, { 100, 5 }, { 15, 5 })
+            end)
+
+            it("layout", function()
+                assert.widget_layout(layout, { 100, 5 }, {
+                    p(first,  0, 0, 100, 5),
+                    p(second, 0, 0, 100, 5),
+                    p(third,  0, 0, 100, 5),
+                })
+            end)
+        end)
+    end)
+
+    describe("emitting signals", function()
+        local layout_changed
+        before_each(function()
+            layout:connect_signal("widget::layout_changed", function()
+                layout_changed = layout_changed + 1
+            end)
+            layout_changed = 0
+        end)
+
+        it("add", function()
+            local w1, w2 = base.empty_widget(), base.empty_widget()
+            assert.is.equal(layout_changed, 0)
+            layout:add(w1)
+            assert.is.equal(layout_changed, 1)
+            layout:add(w2)
+            assert.is.equal(layout_changed, 2)
+            layout:add(w2)
+            assert.is.equal(layout_changed, 3)
+        end)
+
+        it("set_spacing", function()
+            assert.is.equal(layout_changed, 0)
+            layout:set_spacing(0)
+            assert.is.equal(layout_changed, 0)
+            layout:set_spacing(5)
+            assert.is.equal(layout_changed, 1)
+            layout:set_spacing(2)
+            assert.is.equal(layout_changed, 2)
+            layout:set_spacing(2)
+            assert.is.equal(layout_changed, 2)
+        end)
+
+        it("reset", function()
+            assert.is.equal(layout_changed, 0)
+            layout:add(base.make_widget())
+            assert.is.equal(layout_changed, 1)
+            layout:reset()
+            assert.is.equal(layout_changed, 2)
+        end)
+    end)
+
+    it("set_children", function()
+        local w1, w2 = base.empty_widget(), base.empty_widget()
+
+        assert.is.same({}, layout:get_children())
+
+        layout:add(w1)
+        assert.is.same({ w1 }, layout:get_children())
+
+        layout:add(w2)
+        assert.is.same({ w1, w2 }, layout:get_children())
+
+        layout:reset()
+        assert.is.same({}, layout:get_children())
+    end)
+end)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
+

spec/wibox/widget/slider_spec.lua

@@ -12,6 +12,14 @@ describe("wibox.widget.slider", function()
         widget = slider()
     end)
 
+    describe("constructor", function()
+        it("applies arguments", function()
+            widget = slider({ value = 10 })
+
+            assert.is.equal(widget.value, 10)
+        end)
+    end)
+
     describe("signal property::value", function()
         local property_value = nil
         before_each(function()

tests/_client.lua

@@ -1,5 +1,10 @@
 local spawn = require("awful.spawn")
 
+local lua_executable = os.getenv("LUA")
+if lua_executable == nil or lua_executable == "" then
+    lua_executable = "lua"
+end
+
 -- This file provide a simple, yet flexible, test client.
 -- It is used to test the `ruled.client`
 
@@ -106,7 +111,7 @@ local pipe
 local function init()
     if initialized then return end
     initialized = true
-    local cmd = { "lua", "-e", test_client_source }
+    local cmd = { lua_executable, "-e", test_client_source }
     local _, _, stdin, stdout, stderr = awesome.spawn(cmd, false, true, true, true)
     pipe = Gio.UnixOutputStream.new(stdin, true)
     stdout = Gio.UnixInputStream.new(stdout, true)

tests/examples/CMakeLists.txt

@@ -17,7 +17,7 @@ endif()
 cmake_minimum_required(VERSION 3.0.0)
 
 # Get and update the LUA_PATH so the scripts can be executed without awesome.
-execute_process(COMMAND lua -e "p = package.path:gsub(';', '\\\\;'); io.stdout:write(p)"
+execute_process(COMMAND ${LUA_EXECUTABLE} -e "p = package.path:gsub(';', '\\\\;'); io.stdout:write(p)"
     OUTPUT_VARIABLE "LUA_PATH_")
 
 # Allow to use the example tests by themselves.
@@ -32,7 +32,7 @@ endif()
 
 if (DO_COVERAGE)
   execute_process(
-    COMMAND env "SOURCE_DIRECTORY=${TOP_SOURCE_DIR}" lua -e "require('luacov.runner')('${TOP_SOURCE_DIR}/.luacov')"
+    COMMAND env "SOURCE_DIRECTORY=${TOP_SOURCE_DIR}" ${LUA_EXECUTABLE} -e "require('luacov.runner')('${TOP_SOURCE_DIR}/.luacov')"
     RESULT_VARIABLE TEST_RESULT
     ERROR_VARIABLE  TEST_ERROR
     ERROR_STRIP_TRAILING_WHITESPACE)
@@ -40,9 +40,9 @@ if (DO_COVERAGE)
     message(${TEST_ERROR})
     message(FATAL_ERROR "Failed to run luacov.runner.")
   endif()
-  set(LUA_COV_RUNNER lua "-erequire('luacov.runner')('${TOP_SOURCE_DIR}/.luacov')")
+  set(LUA_COV_RUNNER ${LUA_EXECUTABLE} "-erequire('luacov.runner')('${TOP_SOURCE_DIR}/.luacov')")
 else()
-  set(LUA_COV_RUNNER lua)
+  set(LUA_COV_RUNNER ${LUA_EXECUTABLE})
 endif()
 
 if (STRICT_TESTS)

tests/examples/awful/client/border_width.lua

@@ -0,0 +1,85 @@
+--DOC_NO_USAGE --DOC_GEN_IMAGE --DOC_ASTERISK
+local awful     = require("awful") --DOC_HIDE
+local wibox     = require("wibox") --DOC_HIDE
+local beautiful = require("beautiful")
+
+screen[1]._resize {width = 480, height = 200} --DOC_HIDE
+
+local wb = awful.wibar { position = "top" }--DOC_HIDE
+
+--DOC_HIDE Create the same number of tags as the default config
+awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.layouts[1]) --DOC_HIDE
+
+--DOC_HIDE Only bother with widgets that are visible by default
+local mykeyboardlayout = awful.widget.keyboardlayout() --DOC_HIDE
+local mytextclock = wibox.widget.textclock() --DOC_HIDE
+local mytaglist = awful.widget.taglist(screen[1], awful.widget.taglist.filter.all, {}) --DOC_HIDE
+local mytasklist = awful.widget.tasklist(screen[1], awful.widget.tasklist.filter.currenttags, {}) --DOC_HIDE
+
+client.connect_signal("request::titlebars", function(c)--DOC_HIDE
+    local top_titlebar = awful.titlebar(c, {--DOC_HIDE
+        height    = 20,--DOC_HIDE
+        bg_normal = beautiful.bg_normal,--DOC_HIDE
+    })--DOC_HIDE
+
+    top_titlebar : setup {--DOC_HIDE
+        { -- Left--DOC_HIDE
+            awful.titlebar.widget.iconwidget(c),--DOC_HIDE
+            layout  = wibox.layout.fixed.horizontal--DOC_HIDE
+        },--DOC_HIDE
+        { -- Middle--DOC_HIDE
+            { -- Title--DOC_HIDE
+                align  = "center",--DOC_HIDE
+                widget = awful.titlebar.widget.titlewidget(c)--DOC_HIDE
+            },--DOC_HIDE
+            layout  = wibox.layout.flex.horizontal--DOC_HIDE
+        },--DOC_HIDE
+        { -- Right--DOC_HIDE
+            awful.titlebar.widget.floatingbutton (c),--DOC_HIDE
+            awful.titlebar.widget.maximizedbutton(c),--DOC_HIDE
+            awful.titlebar.widget.stickybutton   (c),--DOC_HIDE
+            awful.titlebar.widget.ontopbutton    (c),--DOC_HIDE
+            awful.titlebar.widget.closebutton    (c),--DOC_HIDE
+            layout = wibox.layout.fixed.horizontal()--DOC_HIDE
+        },--DOC_HIDE
+        layout = wibox.layout.align.horizontal--DOC_HIDE
+    }--DOC_HIDE
+end)--DOC_HIDE
+
+
+wb:setup { --DOC_HIDE
+    layout = wibox.layout.align.horizontal, --DOC_HIDE
+    { --DOC_HIDE
+        mytaglist, --DOC_HIDE
+        layout = wibox.layout.fixed.horizontal, --DOC_HIDE
+    }, --DOC_HIDE
+    mytasklist, --DOC_HIDE
+    { --DOC_HIDE
+        layout = wibox.layout.fixed.horizontal, --DOC_HIDE
+        mykeyboardlayout, --DOC_HIDE
+        mytextclock, --DOC_HIDE
+    }, --DOC_HIDE
+} --DOC_HIDE
+
+require("gears.timer").run_delayed_calls_now()--DOC_HIDE
+
+local function gen_client(label)--DOC_HIDE
+    local c = client.gen_fake {hide_first=true} --DOC_HIDE
+
+    c:geometry {--DOC_HIDE
+        x      = 105,--DOC_HIDE
+        y      = 60,--DOC_HIDE
+        height = 60,--DOC_HIDE
+        width  = 230,--DOC_HIDE
+    }--DOC_HIDE
+    c._old_geo = {c:geometry()} --DOC_HIDE
+    c:set_label(label) --DOC_HIDE
+    c:emit_signal("request::titlebars")--DOC_HIDE
+    return c --DOC_HIDE
+end --DOC_HIDE
+
+    local c = gen_client("A manually set border_color") --DOC_HIDE
+    c.border_color = "#ff00ff"
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
+

tests/examples/awful/placement/aero_snap.lua

@@ -0,0 +1,33 @@
+--DOC_HIDE_ALL
+--DOC_GEN_IMAGE
+local placement = require("awful.placement")
+screen[1]._resize {width = 180, height = 120} --DOC_HIDE
+screen._add_screen {x = 190, y = 0, width = 180, height = 120} --DOC_HIDE
+screen._add_screen {x = 380, y = 0, width = 180, height = 120} --DOC_HIDE
+
+for _, pos in ipairs{"left", "right"} do
+    local c1 = client.gen_fake {x = 80, y = 55, width=78, height=50}
+    placement.align(client.focus, {position = pos, honor_workarea=true})
+    c1:_hide_all()
+    placement.maximize_vertically(client.focus, {position = pos, honor_workarea=true})
+    c1:set_label(pos)
+end
+
+for _, pos in ipairs{"top", "bottom"} do
+    local c1 = client.gen_fake {x = 80, y = 55, width=75, height=48,screen=screen[2]}
+    placement.align(client.focus, {position = pos, honor_workarea=true})
+    c1:_hide_all()
+    placement.maximize_horizontally(client.focus, {position = pos, honor_workarea=true})
+    c1:set_label(pos)
+end
+
+for _, pos in ipairs{"top_left", "top_right", "bottom_left", "bottom_right"} do
+    local c1 = client.gen_fake {x = 280, y = 55, width=79, height=48, screen=screen[3]}
+    c1:_hide_all()
+    placement.align(client.focus, {position = pos, honor_workarea=true})
+    c1:set_label(pos)
+end
+
+return {hide_lines=true}
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80