C code: Move docs for signals away from signal_add()

Signed-off-by: Uli Schlachter <psychon@znc.in>
2016-06-04 17:39:14 +02:00 · 2016-06-04 17:39:14 +02:00 · e5f9ec4723
parent 7830cf076b
commit e5f9ec4723
10 changed files with 341 additions and 264 deletions
--- a/luaa.c
+++ b/luaa.c
@ -67,6 +67,54 @@ extern const struct luaL_Reg awesome_root_lib[];
 extern const struct luaL_Reg awesome_mouse_methods[];
 extern const struct luaL_Reg awesome_mouse_meta[];

+/** A call into the lua code aborted with an error
+ * @signal debug::error
+ */
+
+/** A deprecated lua function was called
+ * @signal debug::deprecation
+ */
+
+/** An invalid key was read from an object (e.g. c.foo)
+ * @signal debug::index::miss
+ */
+
+/** An invalid key was written to an object (e.g. c.foo = "bar")
+ * @signal debug::newindex::miss
+ */
+
+/**
+ * @signal systray::update
+ */
+
+/**
+ * @signal wallpaper_changed
+ */
+
+/**
+ * @signal xkb::map_changed
+ */
+
+/**
+ * @signal xkb::group_changed
+ */
+
+/**
+ * @signal refresh
+ */
+
+/**
+ * @signal startup
+ */
+
+/**
+ * @signal exit
+ */
+
+/**
+ * @signal screen::change
+ */
+
 /** Path to config file */
 static char *conffile;

@ -676,53 +724,17 @@ luaA_init(xdgHandle* xdg)

    lua_pop(L, 2); /* pop "package" and "package.loaded" */

-    /** A call into the lua code aborted with an error
-     * @signal debug::error
-     */
    signal_add(&global_signals, "debug::error");
-    /** A deprecated lua function was called
-     * @signal debug::deprecation
-     */
    signal_add(&global_signals, "debug::deprecation");
-    /** An invalid key was read from an object (e.g. c.foo)
-     * @signal debug::index::miss
-     */
    signal_add(&global_signals, "debug::index::miss");
-    /** An invalid key was written to an object (e.g. c.foo = "bar")
-     * @signal debug::newindex::miss
-     */
    signal_add(&global_signals, "debug::newindex::miss");
-    /**
-     * @signal systray::update
-     */
    signal_add(&global_signals, "systray::update");
-    /**
-     * @signal wallpaper_changed
-     */
    signal_add(&global_signals, "wallpaper_changed");
-    /**
-     * @signal xkb::map_changed
-     */
    signal_add(&global_signals, "xkb::map_changed");
-    /**
-     * @signal xkb::group_changed
-     */
    signal_add(&global_signals, "xkb::group_changed");
-    /**
-     * @signal refresh
-     */
    signal_add(&global_signals, "refresh");
-    /**
-     * @signal startup
-     */
    signal_add(&global_signals, "startup");
-    /**
-     * @signal exit
-     */
    signal_add(&global_signals, "exit");
-    /**
-     * @signal screen::change
-     */
    signal_add(&global_signals, "screen::change");
 }

--- a/objects/button.c
+++ b/objects/button.c
@ -59,6 +59,24 @@
 * @function set_newindex_miss_handler
 */

+/** When bound mouse button + modifiers are pressed.
+ * @param ... One or more arguments are possible
+ * @signal .press
+ */
+
+/** When property changes.
+ * @signal property::button
+ */
+
+/** When property changes.
+ * @signal property::modifiers
+ */
+
+/** When bound mouse button + modifiers are pressed.
+ * @param ... One or more arguments are possible
+ * @signal .release
+ */
+
 /** Create a new mouse button bindings.
 * \param L The Lua VM state.
 * \return The number of elements pushed on stack.
@ -161,23 +179,9 @@ button_class_setup(lua_State *L)
                            (lua_class_propfunc_t) luaA_button_get_modifiers,
                            (lua_class_propfunc_t) luaA_button_set_modifiers);

-    /** When bound mouse button + modifiers are pressed.
-     * @param ... One or more arguments are possible
-     * @signal .press
-     */
    signal_add(&button_class.signals, "press");
-    /** When property changes.
-     * @signal property::button
-     */
    signal_add(&button_class.signals, "property::button");
-    /** When property changes.
-     * @signal property::modifiers
-     */
    signal_add(&button_class.signals, "property::modifiers");
-    /** When bound mouse button + modifiers are pressed.
-     * @param ... One or more arguments are possible
-     * @signal .release
-     */
    signal_add(&button_class.signals, "release");
 }

--- a/objects/client.c
+++ b/objects/client.c
@ -109,6 +109,100 @@
 * @table object
 */

+/** When a client gains focus.
+ * @signal .focus
+ */
+
+/** Before manage, after unmanage, and when clients swap.
+ * @signal .list
+ */
+
+/** When 2 clients are swapped
+ * @tparam client client The other client
+ * @tparam boolean is_source If self is the source or the destination of the swap
+ * @signal .swapped
+ */
+
+/**
+ * @signal .manage
+ */
+
+/**
+ * @signal button::press
+ */
+
+/**
+ * @signal button::release
+ */
+
+/**
+ * @signal mouse::enter
+ */
+
+/**
+ * @signal mouse::leave
+ */
+
+/**
+ * @signal mouse::move
+ */
+
+/**
+ * @signal property::window
+ */
+
+/** When a client should get activated (focused and/or raised).
+ *
+ * Default implementation: `awful.ewmh.activate`.
+ * @signal request::activate
+ * @tparam string context The context where this signal was used.
+ * @tparam[opt] table hints A table with additional hints:
+ * @tparam[opt=false] boolean hints.raise should the client be raised?
+ */
+
+/**
+ * @signal request::geometry
+ * @tparam client c The client
+ * @tparam string context Why and what to resize. This is used for the
+ * handlers to know if they are capable of applying the new geometry.
+ * @tparam[opt={}] table Additional arguments. Each context handler may
+ * interpret this differently.
+ */
+
+/**
+ * @signal request::tag
+ */
+
+/**
+ * @signal request::urgent
+ */
+
+/** When a client gets tagged.
+ * @signal .tagged
+ * @tag t The tag object.
+ */
+
+/** When a client gets unfocused.
+ * @signal .unfocus
+ */
+
+/**
+ * @signal .unmanage
+ */
+
+/** When a client gets untagged.
+ * @signal .untagged
+ * @tag t The tag object.
+ */
+
+/**
+ * @signal .raised
+ */
+
+/**
+ * @signal .lowered
+ */
+
 /**
 * The focused `client` or nil (in case there is none).
 *
@ -3336,46 +3430,15 @@ client_class_setup(lua_State *L)
                            (lua_class_propfunc_t) luaA_client_get_first_tag,
                            NULL);

-    /** When a client gains focus.
-     * @signal .focus
-     */
    signal_add(&client_class.signals, "focus");
-    /** Before manage, after unmanage, and when clients swap.
-     * @signal .list
-     */
    signal_add(&client_class.signals, "list");
-    /** When 2 clients are swapped
-     * @tparam client client The other client
-     * @tparam boolean is_source If self is the source or the destination of the swap
-     * @signal .swapped
-     */
    signal_add(&client_class.signals, "swapped");
-    /**
-     * @signal .manage
-     */
    signal_add(&client_class.signals, "manage");
-    /**
-     * @signal button::press
-     */
    signal_add(&client_class.signals, "button::press");
-    /**
-     * @signal button::release
-     */
    signal_add(&client_class.signals, "button::release");
-    /**
-     * @signal mouse::enter
-     */
    signal_add(&client_class.signals, "mouse::enter");
-    /**
-     * @signal mouse::leave
-     */
    signal_add(&client_class.signals, "mouse::leave");
-    /**
-     * @signal mouse::move
-     */
    signal_add(&client_class.signals, "mouse::move");
-
-    /* Those signals are documented elsewhere */
    signal_add(&client_class.signals, "property::above");
    signal_add(&client_class.signals, "property::below");
    signal_add(&client_class.signals, "property::class");
@ -3416,63 +3479,18 @@ client_class_setup(lua_State *L)
    signal_add(&client_class.signals, "property::type");
    signal_add(&client_class.signals, "property::urgent");
    signal_add(&client_class.signals, "property::width");
-    /**
-     * @signal property::window
-     */
    signal_add(&client_class.signals, "property::window");
    signal_add(&client_class.signals, "property::x");
    signal_add(&client_class.signals, "property::y");
-    /** When a client should get activated (focused and/or raised).
-     *
-     * Default implementation: `awful.ewmh.activate`.
-     * @signal request::activate
-     * @tparam string context The context where this signal was used.
-     * @tparam[opt] table hints A table with additional hints:
-     * @tparam[opt=false] boolean hints.raise should the client be raised?
-     */
    signal_add(&client_class.signals, "request::activate");
-    /**
-     * @signal request::geometry
-     * @tparam client c The client
-     * @tparam string context Why and what to resize. This is used for the
-     * handlers to know if they are capable of applying the new geometry.
-     * @tparam[opt={}] table Additional arguments. Each context handler may
-     * interpret this differently.
-     */
    signal_add(&client_class.signals, "request::geometry");
-    /**
-     * @signal request::tag
-     */
    signal_add(&client_class.signals, "request::tag");
-    /**
-     * @signal request::urgent
-     */
    signal_add(&client_class.signals, "request::urgent");
-    /** When a client gets tagged.
-     * @signal .tagged
-     * @tag t The tag object.
-     */
    signal_add(&client_class.signals, "tagged");
-    /** When a client gets unfocused.
-     * @signal .unfocus
-     */
    signal_add(&client_class.signals, "unfocus");
-    /**
-     * @signal .unmanage
-     */
    signal_add(&client_class.signals, "unmanage");
-    /** When a client gets untagged.
-     * @signal .untagged
-     * @tag t The tag object.
-     */
    signal_add(&client_class.signals, "untagged");
-    /**
-     * @signal .raised
-     */
    signal_add(&client_class.signals, "raised");
-    /**
-     * @signal .lowered
-     */
    signal_add(&client_class.signals, "lowered");
 }

--- a/objects/drawable.c
+++ b/objects/drawable.c
@ -43,6 +43,50 @@
 * @function drawable
 */

+/**
+ * @signal button::press
+ */
+
+/**
+ * @signal button::release
+ */
+
+/**
+ * @signal mouse::enter
+ */
+
+/**
+ * @signal mouse::leave
+ */
+
+/**
+ * @signal mouse::move
+ */
+
+/**
+ * @signal property::geometry
+ */
+
+/**
+ * @signal property::height
+ */
+
+/**
+ * @signal property::width
+ */
+
+/**
+ * @signal property::x
+ */
+
+/**
+ * @signal property::y
+ */
+
+/**
+ * @signal property::surface
+ */
+
 /** Get the number of instances.
 *
 * @return The number of drawable objects alive.
@ -197,49 +241,16 @@ drawable_class_setup(lua_State *L)
                            (lua_class_propfunc_t) luaA_drawable_get_surface,
                            NULL);

-    /**
-     * @signal button::press
-     */
    signal_add(&drawable_class.signals, "button::press");
-    /**
-     * @signal button::release
-     */
    signal_add(&drawable_class.signals, "button::release");
-    /**
-     * @signal mouse::enter
-     */
    signal_add(&drawable_class.signals, "mouse::enter");
-    /**
-     * @signal mouse::leave
-     */
    signal_add(&drawable_class.signals, "mouse::leave");
-    /**
-     * @signal mouse::move
-     */
    signal_add(&drawable_class.signals, "mouse::move");
-    /**
-     * @signal property::geometry
-     */
    signal_add(&drawable_class.signals, "property::geometry");
-    /**
-     * @signal property::height
-     */
    signal_add(&drawable_class.signals, "property::height");
-    /**
-     * @signal property::width
-     */
    signal_add(&drawable_class.signals, "property::width");
-    /**
-     * @signal property::x
-     */
    signal_add(&drawable_class.signals, "property::x");
-    /**
-     * @signal property::y
-     */
    signal_add(&drawable_class.signals, "property::y");
-    /**
-     * @signal property::surface
-     */
    signal_add(&drawable_class.signals, "property::surface");
 }

--- a/objects/drawin.c
+++ b/objects/drawin.c
@ -67,6 +67,50 @@
 * @table drawin
 */

+/**
+ * @signal property::geometry
+ */
+
+/**
+ * @signal property::shape_bounding
+ */
+
+/**
+ * @signal property::shape_clip
+ */
+
+/**
+ * @signal property::border_width
+ */
+
+/**
+ * @signal property::cursor
+ */
+
+/**
+ * @signal property::height
+ */
+
+/**
+ * @signal property::ontop
+ */
+
+/**
+ * @signal property::visible
+ */
+
+/**
+ * @signal property::width
+ */
+
+/**
+ * @signal property::x
+ */
+
+/**
+ * @signal property::y
+ */
+
 /** Get or set mouse buttons bindings to a drawin.
 *
 * @param buttons_table A table of buttons objects, or nothing.
@ -716,49 +760,16 @@ drawin_class_setup(lua_State *L)
                            (lua_class_propfunc_t) luaA_drawin_get_shape_clip,
                            (lua_class_propfunc_t) luaA_drawin_set_shape_clip);

-    /**
-     * @signal property::geometry
-     */
    signal_add(&drawin_class.signals, "property::geometry");
-    /**
-     * @signal property::shape_bounding
-     */
    signal_add(&drawin_class.signals, "property::shape_bounding");
-    /**
-     * @signal property::shape_clip
-     */
    signal_add(&drawin_class.signals, "property::shape_clip");
-    /**
-     * @signal property::border_width
-     */
    signal_add(&drawin_class.signals, "property::border_width");
-    /**
-     * @signal property::cursor
-     */
    signal_add(&drawin_class.signals, "property::cursor");
-    /**
-     * @signal property::height
-     */
    signal_add(&drawin_class.signals, "property::height");
-    /**
-     * @signal property::ontop
-     */
    signal_add(&drawin_class.signals, "property::ontop");
-    /**
-     * @signal property::visible
-     */
    signal_add(&drawin_class.signals, "property::visible");
-    /**
-     * @signal property::width
-     */
    signal_add(&drawin_class.signals, "property::width");
-    /**
-     * @signal property::x
-     */
    signal_add(&drawin_class.signals, "property::x");
-    /**
-     * @signal property::y
-     */
    signal_add(&drawin_class.signals, "property::y");
 }

--- a/objects/key.c
+++ b/objects/key.c
@ -56,6 +56,22 @@
 * @table key
 */

+/**
+ * @signal .press
+ */
+
+/**
+ * @signal property::key
+ */
+
+/**
+ * @signal property::modifiers
+ */
+
+/**
+ * @signal .release
+ */
+
 /** Get the number of instances.
 *
 * @return The number of key objects alive.
@ -358,21 +374,9 @@ key_class_setup(lua_State *L)
                            (lua_class_propfunc_t) luaA_key_get_modifiers,
                            (lua_class_propfunc_t) luaA_key_set_modifiers);

-    /**
-     * @signal .press
-     */
    signal_add(&key_class.signals, "press");
-    /**
-     * @signal property::key
-     */
    signal_add(&key_class.signals, "property::key");
-    /**
-     * @signal property::modifiers
-     */
    signal_add(&key_class.signals, "property::modifiers");
-    /**
-     * @signal .release
-     */
    signal_add(&key_class.signals, "release");
 }

--- a/objects/screen.c
+++ b/objects/screen.c
@ -66,6 +66,20 @@
 *
 */

+/**
+ * @signal .primary_changed
+ */
+
+/**
+ * This signal is emitted when a new screen is added to the current setup.
+ * @signal .added
+ */
+
+/**
+ * This signal is emitted when a screen is removed from the setup.
+ * @signal removed
+ */
+
 /**
  * The primary screen.
  *
@ -1118,19 +1132,8 @@ screen_class_setup(lua_State *L)
    signal_add(&screen_class.signals, "property::workarea");
    signal_add(&screen_class.signals, "property::geometry");
    signal_add(&screen_class.signals, "property::outputs");
-    /**
-     * @signal .primary_changed
-     */
    signal_add(&screen_class.signals, "primary_changed");
-    /**
-     * This signal is emitted when a new screen is added to the current setup.
-     * @signal .added
-     */
    signal_add(&screen_class.signals, "added");
-    /**
-     * This signal is emitted when a screen is removed from the setup.
-     * @signal removed
-     */
    signal_add(&screen_class.signals, "removed");
 }

--- a/objects/tag.c
+++ b/objects/tag.c
@ -42,6 +42,20 @@
 #include "ewmh.h"
 #include "luaa.h"

+/**
+ * @signal request::select
+ */
+
+/** When a client gets tagged with this tag.
+ * @signal tagged
+ * @client c The tagged client.
+ */
+
+/** When a client gets untagged with this tag.
+ * @signal untagged
+ * @client c The untagged client.
+ */
+
 /**
 * Tag name.
 *
@ -415,19 +429,8 @@ tag_class_setup(lua_State *L)
    signal_add(&tag_class.signals, "property::name");
    signal_add(&tag_class.signals, "property::selected");
    signal_add(&tag_class.signals, "property::activated");
-    /**
-     * @signal request::select
-     */
    signal_add(&tag_class.signals, "request::select");
-    /** When a client gets tagged with this tag.
-     * @signal tagged
-     * @client c The tagged client.
-     */
    signal_add(&tag_class.signals, "tagged");
-    /** When a client gets untagged with this tag.
-     * @signal untagged
-     * @client c The untagged client.
-     */
    signal_add(&tag_class.signals, "untagged");
 }

--- a/objects/window.c
+++ b/objects/window.c
@ -27,6 +27,30 @@
 * @classmod xproperties
 */

+/**
+ * @signal property::border_color
+ */
+
+/**
+ * @signal property::border_width
+ */
+
+/**
+ * @signal property::buttons
+ */
+
+/**
+ * @signal property::opacity
+ */
+
+/**
+ * @signal property::struts
+ */
+
+/**
+ * @signal property::type
+ */
+
 #include "objects/window.h"
 #include "common/atoms.h"
 #include "common/xutil.h"
@ -520,29 +544,11 @@ window_class_setup(lua_State *L)
                            (lua_class_propfunc_t) luaA_window_get_border_width,
                            (lua_class_propfunc_t) luaA_window_set_border_width);

-    /**
-     * @signal property::border_color
-     */
    signal_add(&window_class.signals, "property::border_color");
-    /**
-     * @signal property::border_width
-     */
    signal_add(&window_class.signals, "property::border_width");
-    /**
-     * @signal property::buttons
-     */
    signal_add(&window_class.signals, "property::buttons");
-    /**
-     * @signal property::opacity
-     */
    signal_add(&window_class.signals, "property::opacity");
-    /**
-     * @signal property::struts
-     */
    signal_add(&window_class.signals, "property::struts");
-    /**
-     * @signal property::type
-     */
    signal_add(&window_class.signals, "property::type");
 }

--- a/spawn.c
+++ b/spawn.c
@ -27,6 +27,31 @@
 * @module awesome
 */

+/** For some reason the application aborted startup
+ * @param arg Table which only got the "id" key set
+ * @signal spawn::canceled
+ */
+
+/** When one of the fields from the @{spawn::initiated} table changes
+ * @param arg Table which describes the spawn event
+ * @signal spawn::change
+ */
+
+/** An application finished starting
+ * @param arg Table which only got the "id" key set
+ * @signal spawn::completed
+ */
+
+/** When a new client is beginning to start
+ * @param arg Table which describes the spawn event
+ * @signal spawn::initiated
+ */
+
+/** An application started a spawn event but didn't start in time.
+ * @param arg Table which only got the "id" key set
+ * @signal spawn::timeout
+ */
+
 #include "spawn.h"

 #include <unistd.h>
@ -245,30 +270,10 @@ spawn_init(void)
                                                  spawn_monitor_event,
                                                  NULL, NULL);

-    /** For some reason the application aborted startup
-     * @param arg Table which only got the "id" key set
-     * @signal spawn::canceled
-     */
    signal_add(&global_signals, "spawn::canceled");
-    /** When one of the fields from the @{spawn::initiated} table changes
-     * @param arg Table which describes the spawn event
-     * @signal spawn::change
-     */
    signal_add(&global_signals, "spawn::change");
-    /** An application finished starting
-     * @param arg Table which only got the "id" key set
-     * @signal spawn::completed
-     */
    signal_add(&global_signals, "spawn::completed");
-    /** When a new client is beginning to start
-     * @param arg Table which describes the spawn event
-     * @signal spawn::initiated
-     */
    signal_add(&global_signals, "spawn::initiated");
-    /** An application started a spawn event but didn't start in time.
-     * @param arg Table which only got the "id" key set
-     * @signal spawn::timeout
-     */
    signal_add(&global_signals, "spawn::timeout");
 }