From e5f9ec47232e7635c46975091305638b8fb7e5c5 Mon Sep 17 00:00:00 2001 From: Uli Schlachter Date: Sat, 4 Jun 2016 17:39:14 +0200 Subject: [PATCH] C code: Move docs for signals away from signal_add() Signed-off-by: Uli Schlachter --- luaa.c | 84 ++++++++++++---------- objects/button.c | 32 +++++---- objects/client.c | 170 +++++++++++++++++++++++++-------------------- objects/drawable.c | 77 +++++++++++--------- objects/drawin.c | 77 +++++++++++--------- objects/key.c | 28 ++++---- objects/screen.c | 25 ++++--- objects/tag.c | 25 ++++--- objects/window.c | 42 ++++++----- spawn.c | 45 ++++++------ 10 files changed, 341 insertions(+), 264 deletions(-) diff --git a/luaa.c b/luaa.c index c647fc451..27238b78b 100644 --- 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"); } diff --git a/objects/button.c b/objects/button.c index 1300ca8f6..ce45a2f99 100644 --- 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"); } diff --git a/objects/client.c b/objects/client.c index 69f5be809..f9c92e2ec 100644 --- 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"); } diff --git a/objects/drawable.c b/objects/drawable.c index 189d3b5c5..63fb36c0c 100644 --- 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"); } diff --git a/objects/drawin.c b/objects/drawin.c index 33dd66e01..c314aac8c 100644 --- 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"); } diff --git a/objects/key.c b/objects/key.c index 2b7bfa079..c3af2c093 100644 --- 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"); } diff --git a/objects/screen.c b/objects/screen.c index f1ad03a02..6771a2672 100644 --- 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"); } diff --git a/objects/tag.c b/objects/tag.c index a0512a4ca..8e8fab3fd 100644 --- 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"); } diff --git a/objects/window.c b/objects/window.c index 2c02ac0fe..3ddeb82ee 100644 --- 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"); } diff --git a/spawn.c b/spawn.c index cbd4a0049..b289b7f45 100644 --- 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 @@ -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"); }