From 3876b182403b3ee6287b3812f22b751f10ab17ea Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Sat, 21 Oct 2017 01:54:36 +0200 Subject: [PATCH] doc: Add missing C-object documentation and fix some papercuts. Ref: https://github.com/awesomeWM/awesome/issues/1373 --- docs/common/cobject.ldoc | 24 ++++++++++++++++++++++++ docs/common/object.ldoc | 26 ++++++++++++++------------ lib/awful/wibox.lua | 4 +++- lib/wibox/layout/align.lua | 2 ++ lib/wibox/layout/fixed.lua | 4 ++-- objects/button.c | 2 ++ objects/client.c | 24 +++++++++++++++++++++++- objects/key.c | 2 ++ objects/screen.c | 28 +++++++++++++++++++++++++--- objects/tag.c | 2 ++ 10 files changed, 99 insertions(+), 19 deletions(-) create mode 100644 docs/common/cobject.ldoc diff --git a/docs/common/cobject.ldoc b/docs/common/cobject.ldoc new file mode 100644 index 00000000..dcacb3a8 --- /dev/null +++ b/docs/common/cobject.ldoc @@ -0,0 +1,24 @@ +*/ + +/** Disconnect from a signal. + * @tparam string name The name of the signal. + * @tparam function func The callback that should be disconnected. + * @function disconnect_signal + */ + +/** Emit a signal. + * + * @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 that are given to emit_signal(). + * @function emit_signal + */ + +/** Connect to a signal. + * @tparam string name The name of the signal. + * @tparam function func The callback to call when the signal is emitted. + * @function connect_signal + */ + +/* diff --git a/docs/common/object.ldoc b/docs/common/object.ldoc index e3f11100..b75fe61c 100644 --- a/docs/common/object.ldoc +++ b/docs/common/object.ldoc @@ -1,28 +1,30 @@ ---- Disconnect to a signal. --- @tparam string name The name of the signal --- @tparam function func The callback that should be disconnected +--- Disconnect from a signal. +-- @tparam string name The name of the signal. +-- @tparam function func The callback that should be disconnected. -- @function disconnect_signal --- Emit a signal. -- --- @tparam string name The name of the signal +-- @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 --- that are given to emit_signal() +-- function receives the object as first argument and then any extra +-- arguments that are given to emit_signal(). -- @function emit_signal --- Connect to a signal. --- @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. -- @function connect_signal ---- Connect to a signal weakly. This allows the callback function to be garbage --- collected and automatically disconnects the signal when that happens. +--- Connect to a signal weakly. +-- +-- This allows the callback function to be garbage collected and +-- 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 +-- @tparam string name The name of the signal. +-- @tparam function func The callback to call when the signal is emitted. -- @function weak_connect_signal diff --git a/lib/awful/wibox.lua b/lib/awful/wibox.lua index f1a754fb..cbd78306 100644 --- a/lib/awful/wibox.lua +++ b/lib/awful/wibox.lua @@ -1,5 +1,7 @@ --------------------------------------------------------------------------- ---- This module is deprecated and has been renamed `awful.wibar` +--- This module is deprecated and has been renamed to `awful.wibar` +-- +-- This only deprecates `awful.wibox`, but not @{wibox}. -- -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2016 Emmanuel Lepage Vallee diff --git a/lib/wibox/layout/align.lua b/lib/wibox/layout/align.lua index 00042063..afb12dba 100644 --- a/lib/wibox/layout/align.lua +++ b/lib/wibox/layout/align.lua @@ -309,6 +309,8 @@ function align.vertical(top, middle, bottom) return ret end +--@DOC_fixed_COMMON@ + --@DOC_widget_COMMON@ --@DOC_object_COMMON@ diff --git a/lib/wibox/layout/fixed.lua b/lib/wibox/layout/fixed.lua index 95b91e6a..ee7a56ae 100644 --- a/lib/wibox/layout/fixed.lua +++ b/lib/wibox/layout/fixed.lua @@ -14,8 +14,6 @@ local gtable = require("gears.table") local fixed = {} ---@DOC_fixed_COMMON@ - -- Layout a fixed layout. Each widget gets just the space it asks for. -- @param context The context in which we are drawn. -- @param width The available width. @@ -353,6 +351,8 @@ function fixed:get_spacing() return self._private.spacing or 0 end +--@DOC_fixed_COMMON@ + --@DOC_widget_COMMON@ --@DOC_object_COMMON@ diff --git a/objects/button.c b/objects/button.c index 3045cd4f..846ed7d4 100644 --- a/objects/button.c +++ b/objects/button.c @@ -179,4 +179,6 @@ button_class_setup(lua_State *L) (lua_class_propfunc_t) luaA_button_set_modifiers); } +/* @DOC_cobject_COMMON@ */ + // vim: filetype=c:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/objects/client.c b/objects/client.c index e3c1ffe3..81720563 100644 --- a/objects/client.c +++ b/objects/client.c @@ -371,7 +371,26 @@ */ /** - * The client icon. + * The client icon as a surface. + * + * This property holds the client icon closest to the size configured via + * @{awesome.set_preferred_icon_size}. + * + * It is not a path or an "real" file. Rather, it is already a bitmap surface. + * + * Typically you would want to use @{awful.widget.clienticon} to get this as a + * widget. + * + * Working with icons is tricky because their surfaces do not use reference + * counting correctly. If `gears.surface(c.icon)` is called multiple time on + * the same icon, it will cause a double-free error and Awesome will crash. To + * get a copy of the icon, you can use: + * + * local s = gears.surface(c.icon) + * local img = cairo.ImageSurface.create(cairo.Format.ARGB32, s:get_width(), s:get_height()) + * local cr = cairo.Context(img) + * cr:set_source_surface(s, 0, 0) + * cr:paint() * * **Signal:** * @@ -379,6 +398,7 @@ * * @property icon * @param surface + * @usage local ib = wibox.widget.imagebox(c.icon) */ /** @@ -3787,4 +3807,6 @@ client_class_setup(lua_State *L) NULL); } +/* @DOC_cobject_COMMON@ */ + // vim: filetype=c:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/objects/key.c b/objects/key.c index 9f27488f..94f73eba 100644 --- a/objects/key.c +++ b/objects/key.c @@ -374,4 +374,6 @@ key_class_setup(lua_State *L) (lua_class_propfunc_t) luaA_key_set_modifiers); } +/* @DOC_cobject_COMMON@ */ + // vim: filetype=c:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/objects/screen.c b/objects/screen.c index 62e6479c..405cdb36 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -117,14 +117,34 @@ */ /** - * The screen number. + * The internal screen number. * - * An integer greater than 1 and smaller than `screen.count()`. Please note that - * the screen order isn't always mirroring the screen logical position. + * * The indeces are a continuous sequence from 1 to `screen.count()`. + * * It is **NOT** related to the actual screen position relative to each + * other. + * * 1 is **NOT** necessarily the primary screen. + * * When screens are added and removed indices **CAN** change. + * + * If you really want to keep an array of screens you should use something + * along: + * + * local myscreens = setmetatable({}. {__mode="k"}) + * myscreens[ screen[1] ] = "mydata" + * + * But it might be a better option to simply store the data directly in the + * screen object as: + * + * screen[1].mydata = "mydata" + * + * Remember that screens are also objects, so if you only want to store a simple + * property, you can do it directly: + * + * screen[1].answer = 42 * * **Immutable:** true * @property index * @param integer + * @see screen */ /** @@ -1318,4 +1338,6 @@ screen_class_setup(lua_State *L) NULL); } +/* @DOC_cobject_COMMON@ */ + // vim: filetype=c:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/objects/tag.c b/objects/tag.c index ed0ad2c9..9b289dee 100644 --- a/objects/tag.c +++ b/objects/tag.c @@ -578,4 +578,6 @@ tag_class_setup(lua_State *L) (lua_class_propfunc_t) luaA_tag_set_activated); } +/* @DOC_cobject_COMMON@ */ + // vim: filetype=c:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80