Merge pull request #3347 from sclu1034/feature/docs

API doc improvements

docs/07-my-first-awesome.md

@@ -65,8 +65,13 @@ overview now also provides a cheat sheet for controlling Vim.
 
 ## Change the theme
 
-Awesome has four builtin themes you can choose from: *default*, *sky*,
-*xresources*, and *zenburn*.
+Awesome has multiple builtin themes you can choose from:
+
+* *default*
+* *gtk*
+* *sky*
+* *xresources*
+* *zenburn*
 
 To change the theme, open your `rc.lua`, find this line near the beginning of
 the file, and change `default` to one of the other values mentioned:

docs/90-FAQ.md

@@ -53,6 +53,19 @@ provide a theme daemon. For more information about how to manage the
 look and feel of applications, refer to the
 [Arch Linux Wiki](https://wiki.archlinux.org/index.php/Category:Eye_candy).
 
+### Awesome doesn't show up on my login screen
+
+There have been cases where Awesome wasn't correctly registered with the display manager,
+usually due to a missing `.desktop` file.
+
+To fix such issues, copy `awesome.desktop` from the root of [the repository](https://github.com/awesomeWM/awesome/) to `/usr/share/xsessions/`.
+
+```shell
+curl https://raw.githubusercontent.com/awesomeWM/awesome/master/awesome.desktop | sudo tee /usr/share/xsessions/awesome.desktop
+```
+
+If you installed Awesome through a package manager, you might want to check if the package includes that file and, if not, notify the maintainer to add it as appropriate.
+
 ## Configuration
 
 ### How to change the default window management layout?

docs/common/fixed.ldoc

@@ -58,7 +58,7 @@
 -- @emitstparam widget::swapped number index1 The second index.
 -- @interface layout
 
---- Reset a ratio layout. This removes all widgets from the layout.
+--- Reset the layout. This removes all widgets from the layout.
 -- @method reset
 -- @emits widget::reset
 -- @emitstparam widget::reset widget self The layout.

lib/awful/client.lua

@@ -595,18 +595,42 @@ function client.object.move_to_screen(self, s)
     end
 end
 
---- Tag a client with the set of current tags.
+--- Find suitable tags for newly created clients.
+--
+-- In most cases, the functionality you're actually looking for as a user will
+-- either be
+--
+--    c:tags(c.screen.selected_tags)
+--
+-- or
+--
+--    local s = awful.screen.focused()
+--    c:move_to_screen(s)
+--    c:tags(s.selected_tags)
+--
+-- Despite its naming, this is primarily used to tag newly created clients.
+-- As such, this method has no effect when applied to a client that already has
+-- tags assigned (except for emitting `property::tag`).
+--
+-- Additionally, while it is a rare case, if the client's screen has no selected
+-- tags at the point of calling this method, it will fall back to the screen's
+-- full set of tags.
+--
 -- @method to_selected_tags
 -- @see screen.selected_tags
 function client.object.to_selected_tags(self)
     local tags = {}
 
+    -- From the client's current tags, find the ones that
+    -- belong to the client's screen
     for _, t in ipairs(self:tags()) do
         if get_screen(t.screen) == get_screen(self.screen) then
             table.insert(tags, t)
         end
     end
 
+    -- If no tags were found,
+    -- choose the screen's selected tags, if any, or all of the screens tags
     if self.screen then
         if #tags == 0 then
             tags = self.screen.selected_tags
@@ -617,6 +641,7 @@ function client.object.to_selected_tags(self)
         end
     end
 
+    -- Prevent clients from becoming untagged
     if #tags ~= 0 then
         self:tags(tags)
     end
@@ -1134,10 +1159,13 @@ end
 
 --- Change window factor of a client.
 --
+-- This will emit `property::windowfact` on the specific tag object
+-- `c.screen.selected_tag`.
+--
 -- @legacylayout awful.client.incwfact
--- @tparam number add Amount to increase/decrease the client's window factor.
+-- @tparam number add Amount to increase/decrease the client's window factor by.
 --   Should be between `-current_window_factor` and something close to
---   infinite.  The normalisation then ensures that the sum of all factors is 1.
+--   infinite. Normalisation then ensures that the sum of all factors is 1.
 -- @tparam client c the client.
 -- @emits property::windowfact
 function client.incwfact(add, c)

objects/client.c

@@ -750,9 +750,13 @@ lua_class_t client_class;
  * Note that setting this directly will override and disable all related theme
  * variables.
  *
+ * Setting a transparent color (e.g. to implement dynamic borders without size
+ * changes) is supported, but requires the color to be set to `#00000000`
+ * specifically. Other RGB colors with an alpha of `0` won't work.
+ *
  * @property border_color
- * @tparam color border_color Any string, gradients and patterns will be converted to a
- *  cairo pattern.
+ * @tparam color border_color Any string, gradient or pattern definition that
+ *  can be converted to a cairo pattern.
  * @propemits false false
  * @usebeautiful beautiful.border_color_marked The fallback color when the
  *  client is marked.