Merge pull request #3879 from Elv13/2023_xmas_commits_pr1

Fix the documentation warnings

docs/config.ld

@@ -1739,6 +1739,13 @@ local summarize = {
     readonly      = {index = 8, title = "read only"       , count = false},
 }
 
+local no_prefix = {
+    property           = true,
+    signal             = true,
+    clientruleproperty = true,
+    deprecatedproperty = true,
+}
+
 local delimiter_for_tag = {
     usebeautiful  = { "table class='widget_list' border=1", "table", "tr", "tr", {"Theme variable", "Usage"}},
     propbeautiful = { "table class='widget_list' border=1", "table", "tr", "tr", {"Theme variable", "Usage"}},
@@ -2126,7 +2133,11 @@ local function global_init(_ldoc)
                 -- Decorate the item with our customizations.
                 init_custom_types(item)
 
-                -- print(item.description)
+                -- Remove the "namespace" from the signals and properties
+                if no_prefix[item.type] then
+                    local name = item.name:match("%.([^.]+)$")
+                    item.name = name ~= "" and name or item.name
+                end
 
                 if item.summary and not detect_markdown_footguns(item.summary) then
                     print(
@@ -2247,13 +2258,6 @@ local function compare_module_name(input, module)
     return false
 end
 
-local no_prefix = {
-    property           = true,
-    signal             = true,
-    clientruleproperty = true,
-    deprecatedproperty = true,
-}
-
 -- These modules merge the doc of their `awful` siblings.
 local coreclassmap = {
     tag    = "tag<span class='listplusign'> and awful.tag</span>",
@@ -2366,12 +2370,6 @@ custom_display_name_handler = function(item, default_handler)
         item:build_return_groups()
     end
 
-    -- Remove the "namespace" from the signals and properties
-    if no_prefix[item.type] then
-        local name = item.name:match("%.([^.]+)$")
-        return name ~= "" and name or item.name
-    end
-
     -- Handle the left sidebar modules.
     if item.type == "coreclassmod" and coreclassmap[item.name] then
         return coreclassmap[item.name]

lib/awful/screenshot.lua

@@ -440,15 +440,15 @@ end
 -- @tparam[opt=nil] screen|nil screen
 -- @propemits true false
 -- @see mouse.screen
--- @see awful.screen.focused
+-- @see screen.focused
 -- @see screen.primary
 
 --- Get screenshot client.
 --
 -- @property client
--- @tparam[opt=nil] client|nil client
+-- @tparam[opt=nil] client|nil client The client.
 -- @propemits true false
--- @see mouse.client
+-- @see mouse.current_client
 -- @see client.focus
 
 --- Get screenshot geometry.
@@ -891,6 +891,7 @@ end
 -- @method reject
 -- @tparam[opt=nil] string||nil reason The reason why it was rejected. This is
 --  passed to the `"snipping::cancelled"` signal.
+-- @noreturn
 -- @emits snipping::cancelled
 
 function module:reject(reason)

lib/gears/shape.lua

@@ -778,6 +778,7 @@ end
 -- @tparam number height The shape height
 -- @tparam[opt=5] number x_offset The shadow area horizontal offset.
 -- @tparam[opt=5] number y_offset The shadow area vertical offset.
+-- @noreturn
 function module.solid_rectangle_shadow(cr, w, h, x_offset, y_offset)
     x_offset, y_offset = x_offset or 5, y_offset or 5
     w, h = w - math.abs(x_offset), h - math.abs(y_offset)

tests/examples/CMakeLists.txt

@@ -58,6 +58,7 @@ ${TOP_SOURCE_DIR}/lib/?/init.lua\\;\
 ${TOP_SOURCE_DIR}/lib/?\\;\
 ${TOP_SOURCE_DIR}/themes/?.lua\\;\
 ${TOP_SOURCE_DIR}/themes/?\\;\
+${TOP_SOURCE_DIR}/tests/examples/?.lua\\;\
 ${LUA_PATH_}")
 
 # Add the C API shims.

tests/examples/sequences/client/jump_to_urgent1.lua

@@ -6,7 +6,6 @@ local beautiful = require("beautiful")
 require("awful.ewmh")
 screen[1]._resize {x = 0, width = 160, height = 90}
 awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile)
-beautiful.bg_urgent = "#ff0000"
 
 function awful.spawn(name, properties)
     client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50, tags = properties.tags}

tests/examples/shims/beautiful.lua

@@ -49,6 +49,8 @@ local module = {
     bg_normal    = "#6181FF7D",
     bg_focus     = "#AA00FF7D",
     bg_highlight = "#AA00FF7D",
+    bg_urgent    = "#FF00377D",
+    fg_urgent    = "#FFFFFFFF",
     border_color = "#6181FF"  ,
     border_width = 1.5        ,
 

tests/examples/shims/client.lua

@@ -7,6 +7,64 @@ local client, meta = awesome._shim_fake_class()
 
 rawset(client, "_autotags", true)
 
+-- Make sure `awful.client` properties like `floating` get handled by the
+-- miss handler rather than set directly on the object. The reason it's done
+-- than way is ancient and convoluted.
+local native_property_defaults = {
+    -- Layers.
+    ontop     = false,
+    below     = false,
+    above     = false,
+    sticky    = false,
+    urgent    = false,
+    modal     = false,
+    focusable = true,
+    hidden    = false,
+
+    -- Other properties.
+    name             = "",
+    transient_for    = nil,
+    skip_taskbar     = false,
+    type             = "normal",
+    class            = "",
+    instance         = "",
+    role             = "",
+    pid              = 1,
+    leader_window    = nil,
+    machine          = "",
+    icon_name        = "",
+    screen           = nil,
+    minimized        = false,
+    motif_wm_hints   = {},
+    group_window     = nil,
+    icon             = nil,
+    icon_sizes       = {},
+    size_hints_honor = true,
+    size_hints       = {},
+    startup_id       = nil,
+    valid            = true,
+
+    -- The shims can't really handle those properly.
+    shape_bounding        = nil,
+    content               = nil,
+    shape_clip            = nil,
+    shape_input           = nil,
+    client_shape_bounding = nil,
+    client_shape_clip     = nil,
+
+    -- Those have special code.
+    maximized            = nil,
+    fullscreen           = nil,
+    maximized_horizontal = nil,
+    maximized_vertical   = nil,
+
+    -- Those are not really native, but it simplify the shims a lot.
+    x      = 0,
+    y      = 0,
+    width  = 1,
+    height = 1,
+}
+
 -- Keep an history of the geometry for validation and images
 local function push_geometry(c)
     table.insert(c._old_geo, c:geometry())
@@ -76,9 +134,9 @@ function client.gen_fake(args)
     awesome._forward_class(ret, client)
 
     ret._private = {}
-    ret.type = "normal"
+    ret.type = native_property_defaults.type
-    ret.valid = true
+    ret.valid = native_property_defaults.valid
-    ret.size_hints = {}
+    ret.size_hints = native_property_defaults.size_hints
     ret._border_width = 1
     ret._tags = args and args.tags or nil
     ret.icon_sizes = {{16,16}}
@@ -95,10 +153,12 @@ function client.gen_fake(args)
     -- be `nil`.
     ret.transient_for = false
 
-    -- Apply all properties
+    -- Apply the native (capi) properties.
     for k,v in pairs(args or {}) do
+        if native_property_defaults[k] then
             ret[k] = v
         end
+    end
 
     -- Tests should always set a geometry, but just in case
     for _, v in ipairs{"x","y","width","height"} do
@@ -295,14 +355,7 @@ function client.gen_fake(args)
     ret.drawable = ret
 
     -- Make sure the layer properties are not `nil`
-    local defaults = {
+    local defaults = setmetatable({}, {__index = native_property_defaults})
-        ontop     = false,
-        below     = false,
-        above     = false,
-        sticky    = false,
-        urgent    = false,
-        focusable = true,
-    }
 
     -- Declare the deprecated buttons and keys methods.
     function ret:_keys(new)
@@ -352,6 +405,13 @@ function client.gen_fake(args)
         end
     })
 
+    -- Apply non-native (`awful.client`) properties.
+    for k,v in pairs(args or {}) do
+        if (not native_property_defaults[k]) and (not rawget(ret, k)) then
+            ret[k] = v
+        end
+    end
+
     client.emit_signal("request::manage", ret)
 
     --TODO v6 remove this.