From 044d58951e4d72f387377ee75f647d9dc63462f1 Mon Sep 17 00:00:00 2001 From: "Jasper St. Pierre" Date: Wed, 2 Nov 2011 11:34:45 -0400 Subject: [PATCH] Switch to gtk-doc syntax https://bugzilla.gnome.org/show_bug.cgi?id=673752 --- src/compositor/meta-plugin.c | 2 +- src/core/bell.c | 68 +++++---- src/core/bell.h | 12 -- src/core/display.c | 154 ++++++++++---------- src/core/main.c | 64 +++++---- src/core/prefs.c | 53 ++++--- src/core/screen.c | 3 +- src/core/stack.c | 17 ++- src/core/stack.h | 244 +++++++++++++++++-------------- src/core/window-props.c | 14 +- src/core/window-props.h | 64 +++++---- src/core/window.c | 10 +- src/core/workspace.c | 12 +- src/meta/common.h | 1 + src/meta/prefs.h | 7 +- src/meta/workspace.h | 21 +-- src/ui/tabpopup.c | 9 +- src/ui/theme.c | 272 ++++++++++++++++++----------------- 18 files changed, 556 insertions(+), 471 deletions(-) diff --git a/src/compositor/meta-plugin.c b/src/compositor/meta-plugin.c index 475f877f9..f687c0b63 100644 --- a/src/compositor/meta-plugin.c +++ b/src/compositor/meta-plugin.c @@ -396,7 +396,7 @@ meta_plugin_begin_modal (MetaPlugin *plugin, } /** - * meta_plugin_end_modal + * meta_plugin_end_modal: * @plugin: a #MetaPlugin * @timestamp: the time used for releasing grabs * diff --git a/src/core/bell.c b/src/core/bell.c index dbb218831..4f48c6f94 100644 --- a/src/core/bell.c +++ b/src/core/bell.c @@ -23,7 +23,8 @@ */ /** - * \file bell.c Ring the bell or flash the screen + * SECTION:Bell + * @short_description: Ring the bell or flash the screen * * Sometimes, X programs "ring the bell", whatever that means. Mutter lets * the user configure the bell to be audible or visible (aka visual), and @@ -57,6 +58,10 @@ #endif /** + * bell_flash_screen: + * @display: The display which owns the screen (rather redundant) + * @screen: The screen to flash + * * Flashes one entire screen. This is done by making a window the size of the * whole screen (or reusing the old one, if it's still around), mapping it, * painting it white and then black, and then unmapping it. We set saveunder so @@ -65,14 +70,12 @@ * Unlike frame flashes, we don't do fullscreen flashes with a timeout; rather, * we do them in one go, because we don't have to rely on the theme code * redrawing the frame for us in order to do the flash. - * - * \param display The display which owns the screen (rather redundant) - * \param screen The screen to flash - * - * \bug The way I read it, this appears not to do the flash + */ +/* + * Bug: The way I read it, this appears not to do the flash * the first time we flash a particular display. Am I wrong? * - * \bug This appears to destroy our current XSync status. + * Bug: This appears to destroy our current XSync status. */ static void bell_flash_screen (MetaDisplay *display, @@ -137,14 +140,15 @@ bell_flash_screen (MetaDisplay *display, } /** + * bell_flash_fullscreen: + * @display: The display the event came in on + * @xkb_ev: The bell event + * * Flashes one screen, or all screens, in response to a bell event. * If the event is on a particular window, flash the screen that * window is on. Otherwise, flash every screen on this display. * * If the configure script found we had no XKB, this does not exist. - * - * \param display The display the event came in on - * \param xkb_ev The bell event */ #ifdef HAVE_XKB static void @@ -182,17 +186,21 @@ bell_flash_fullscreen (MetaDisplay *display, } /** + * bell_unflash_frame: + * @data: The frame to unflash, cast to a gpointer so it can go into + * a callback function. + * * Makes a frame be not flashed; this is the timeout half of * bell_flash_window_frame(). This is done simply by clearing the * flash flag and queuing a redraw of the frame. * * If the configure script found we had no XKB, this does not exist. * - * \param data The frame to unflash, cast to a gpointer so it can go into - * a callback function. - * \return Always FALSE, so we don't get called again. - * - * \bug This is the parallel to bell_flash_window_frame(), so it should + * Returns: Always FALSE, so we don't get called again. + */ + +/* + * Bug: This is the parallel to bell_flash_window_frame(), so it should * really be called meta_bell_unflash_window_frame(). */ static gboolean @@ -205,6 +213,9 @@ bell_unflash_frame (gpointer data) } /** + * bell_flash_window_frame: + * @window: The window to flash + * * Makes a frame flash and then return to normal shortly afterwards. * This is done by setting a flag so that the theme * code will temporarily draw the frame as focussed if it's unfocussed and @@ -212,8 +223,6 @@ bell_unflash_frame (gpointer data) * that the flag can be unset and the frame re-redrawn. * * If the configure script found we had no XKB, this does not exist. - * - * \param window The window to flash */ static void bell_flash_window_frame (MetaWindow *window) @@ -231,11 +240,12 @@ bell_flash_window_frame (MetaWindow *window) } /** + * bell_flash_frame: + * @display: The display the bell event came in on + * @xkb_ev: The bell event we just received + * * Flashes the frame of the focussed window. If there is no focussed window, * flashes the screen. - * - * \param display The display the bell event came in on - * \param xkb_ev The bell event we just received */ static void bell_flash_frame (MetaDisplay *display, @@ -261,15 +271,18 @@ bell_flash_frame (MetaDisplay *display, } /** + * bell_visual_notify: + * @display: The display the bell event came in on + * @xkb_ev: The bell event we just received + * * Gives the user some kind of visual bell substitute, in response to a * bell event. What this is depends on the "visual bell type" pref. * * If the configure script found we had no XKB, this does not exist. - * - * \param display The display the bell event came in on - * \param xkb_ev The bell event we just received - * - * \bug This should be merged with meta_bell_notify(). + */ + +/* + * Bug: This should be merged with meta_bell_notify(). */ static void bell_visual_notify (MetaDisplay *display, @@ -407,12 +420,13 @@ meta_bell_shutdown (MetaDisplay *display) } /** + * meta_bell_notify_frame_destroy: + * @frame: The frame which is being destroyed + * * Deals with a frame being destroyed. This is important because if we're * using a visual bell, we might be flashing the edges of the frame, and * so we'd have a timeout function waiting ready to un-flash them. If the * frame's going away, we can tell the timeout not to bother. - * - * \param frame The frame which is being destroyed */ void meta_bell_notify_frame_destroy (MetaFrame *frame) diff --git a/src/core/bell.h b/src/core/bell.h index 50f059f04..e9ba84bd2 100644 --- a/src/core/bell.h +++ b/src/core/bell.h @@ -1,17 +1,5 @@ /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */ -/** - * \file bell.h Ring the bell or flash the screen - * - * Sometimes, X programs "ring the bell", whatever that means. Mutter lets - * the user configure the bell to be audible or visible (aka visual), and - * if it's visual it can be configured to be frame-flash or fullscreen-flash. - * We never get told about audible bells; X handles them just fine by itself. - * - * The visual bell was the result of a discussion in Bugzilla here: - * . - */ - /* * Copyright (C) 2002 Sun Microsystems Inc. * diff --git a/src/core/display.c b/src/core/display.c index 676cd566f..c4e93c39f 100644 --- a/src/core/display.c +++ b/src/core/display.c @@ -25,9 +25,10 @@ */ /** - * \file display.c Handles operations on an X display. + * SECTION:MetaDisplay + * @short_description: Handles operations on an X display. * - * The display is represented as a MetaDisplay struct. + * The display is represented as a #MetaDisplay struct. */ #define _XOPEN_SOURCE 600 /* for gethostname() */ @@ -87,7 +88,7 @@ g == META_GRAB_OP_KEYBOARD_ESCAPING_GROUP) /** - * \defgroup pings Pings + * SECTION:pings * * Sometimes we want to see whether a window is responding, * so we send it a "ping" message and see whether it sends us back a "pong" @@ -102,13 +103,13 @@ */ /** + * MetaPingData: + * * Describes a ping on a window. When we send a ping to a window, we build * one of these structs, and it eventually gets passed to the timeout function * or to the function which handles the response from the window. If the window * does or doesn't respond to the ping, we use this information to deal with * these facts; we have a handler function for each. - * - * \ingroup pings */ typedef struct { @@ -150,7 +151,7 @@ enum { static guint display_signals [LAST_SIGNAL] = { 0 }; -/** +/* * The display we're managing. This is a singleton object. (Historically, * this was a list of displays, but there was never any way to add more * than one element to it.) The goofy name is because we don't want it @@ -185,7 +186,7 @@ static void prefs_changed_callback (MetaPreference pref, static void sanity_check_timestamps (MetaDisplay *display, guint32 known_good_timestamp); - + MetaGroup* get_focussed_group (MetaDisplay *display); static void @@ -295,10 +296,10 @@ meta_display_class_init (MetaDisplayClass *klass) /** - * Destructor for MetaPingData structs. Will destroy the - * event source for the struct as well. + * ping_data_free: * - * \ingroup pings + * Destructor for #MetaPingData structs. Will destroy the + * event source for the struct as well. */ static void ping_data_free (MetaPingData *ping_data) @@ -311,14 +312,12 @@ ping_data_free (MetaPingData *ping_data) } /** + * remove_pending_pings_for_window: + * @display: The display the window appears on + * @xwindow: The X ID of the window whose pings we should remove + * * Frees every pending ping structure for the given X window on the * given display. This means that we also destroy the timeouts. - * - * \param display The display the window appears on - * \param xwindow The X ID of the window whose pings we should remove - * - * \ingroup pings - * */ static void remove_pending_pings_for_window (MetaDisplay *display, Window xwindow) @@ -417,14 +416,14 @@ meta_display_init (MetaDisplay *disp) } /** + * meta_display_open: + * * Opens a new display, sets it up, initialises all the X extensions * we will need, and adds it to the list of displays. * - * \return True if the display was opened successfully, and False + * Returns: %TRUE if the display was opened successfully, and %FALSE * otherwise-- that is, if the display doesn't exist or it already * has a window manager. - * - * \ingroup main */ gboolean meta_display_open (void) @@ -1168,14 +1167,16 @@ meta_display_ungrab (MetaDisplay *display) } /** - * Returns the singleton MetaDisplay if "xdisplay" matches the X display it's - * managing; otherwise gives a warning and returns NULL. When we were claiming + * meta_display_for_x_display: + * @xdisplay: An X display + * + * Returns the singleton MetaDisplay if @xdisplay matches the X display it's + * managing; otherwise gives a warning and returns %NULL. When we were claiming * to be able to manage multiple displays, this was supposed to find the * display out of the list which matched that display. Now it's merely an * extra sanity check. * - * \param xdisplay An X display - * \return The singleton X display, or NULL if "xdisplay" isn't the one + * Returns: The singleton X display, or %NULL if @xdisplay isn't the one * we're managing. */ MetaDisplay* @@ -1191,9 +1192,11 @@ meta_display_for_x_display (Display *xdisplay) } /** + * meta_get_display: + * * Accessor for the singleton MetaDisplay. * - * \return The only MetaDisplay there is. This can be NULL, but only + * Returns: The only #MetaDisplay there is. This can be %NULL, but only * during startup. */ MetaDisplay* @@ -1601,19 +1604,18 @@ handle_net_restack_window (MetaDisplay* display, #endif /** + * event_callback: + * @event: The event that just happened + * @data: The #MetaDisplay that events are coming from, cast to a gpointer + * so that it can be sent to a callback + * * This is the most important function in the whole program. It is the heart, * it is the nexus, it is the Grand Central Station of Mutter's world. - * When we create a MetaDisplay, we ask GDK to pass *all* events for *all* + * When we create a #MetaDisplay, we ask GDK to pass *all* events for *all* * windows to this function. So every time anything happens that we might * want to know about, this function gets called. You see why it gets a bit * busy around here. Most of this function is a ginormous switch statement * dealing with all the kinds of events that might turn up. - * - * \param event The event that just happened - * \param data The MetaDisplay that events are coming from, cast to a gpointer - * so that it can be sent to a callback - * - * \ingroup main */ static gboolean event_callback (XEvent *event, @@ -4197,21 +4199,23 @@ meta_display_set_cursor_theme (const char *theme, #endif } -/** +/* * Stores whether syncing is currently enabled. */ static gboolean is_syncing = FALSE; /** + * meta_is_syncing: + * * Returns whether X synchronisation is currently enabled. * - * \return true if we must wait for events whenever we send X requests; - * false otherwise. - * - * \bug This is *only* called by meta_display_open, but by that time + * FIXME: This is *only* called by meta_display_open(), but by that time * we have already turned syncing on or off on startup, and we don't * have any way to do so while Mutter is running, so it's rather * pointless. + * + * Returns: %TRUE if we must wait for events whenever we send X requests; + * %FALSE otherwise. */ gboolean meta_is_syncing (void) @@ -4220,10 +4224,9 @@ meta_is_syncing (void) } /** - * A handy way to turn on synchronisation on or off for every display. + * meta_set_syncing: * - * \bug Of course there is only one display ever anyway, so this can - * be rather hugely simplified. + * A handy way to turn on synchronisation on or off for every display. */ void meta_set_syncing (gboolean setting) @@ -4236,26 +4239,25 @@ meta_set_syncing (gboolean setting) } } -/** +/* * How long, in milliseconds, we should wait after pinging a window * before deciding it's not going to get back to us. */ #define PING_TIMEOUT_DELAY 5000 /** + * meta_display_ping_timeout: + * @data: All the information about this ping. It is a #MetaPingData + * cast to a #gpointer in order to be passable to a timeout function. + * This function will also free this parameter. + * * Does whatever it is we decided to do when a window didn't respond * to a ping. We also remove the ping from the display's list of * pending pings. This function is called by the event loop when the timeout * times out which we created at the start of the ping. * - * \param data All the information about this ping. It is a MetaPingData - * cast to a void* in order to be passable to a timeout function. - * This function will also free this parameter. - * - * \return Always returns false, because this function is called as a - * timeout and we don't want to run the timer again. - * - * \ingroup pings + * Returns: Always returns %FALSE, because this function is called as a + * timeout and we don't want to run the timer again. */ static gboolean meta_display_ping_timeout (gpointer data) @@ -4282,6 +4284,17 @@ meta_display_ping_timeout (gpointer data) } /** + * meta_display_ping_window: + * @display: The #MetaDisplay that the window is on + * @window: The #MetaWindow to send the ping to + * @timestamp: The timestamp of the ping. Used for uniqueness. + * Cannot be CurrentTime; use a real timestamp! + * @ping_reply_func: The callback to call if we get a response. + * @ping_timeout_func: The callback to call if we don't get a response. + * @user_data: Arbitrary data that will be passed to the callback + * function. (In practice it's often a pointer to + * the window.) + * * Sends a ping request to a window. The window must respond to * the request within a certain amount of time. If it does, we * will call one callback; if the time passes and we haven't had @@ -4291,20 +4304,9 @@ meta_display_ping_timeout (gpointer data) * This function returns straight away after setting things up; * the callbacks will be called from the event loop. * - * \param display The MetaDisplay that the window is on - * \param window The MetaWindow to send the ping to - * \param timestamp The timestamp of the ping. Used for uniqueness. - * Cannot be CurrentTime; use a real timestamp! - * \param ping_reply_func The callback to call if we get a response. - * \param ping_timeout_func The callback to call if we don't get a response. - * \param user_data Arbitrary data that will be passed to the callback - * function. (In practice it's often a pointer to - * the window.) + * FIXME: This should probably be a method on windows, rather than displays + * for one of their windows. * - * \bug This should probably be a method on windows, rather than displays - * for one of their windows. - * - * \ingroup pings */ void meta_display_ping_window (MetaDisplay *display, @@ -4412,16 +4414,15 @@ process_request_frame_extents (MetaDisplay *display, } /** + * process_pong_message: + * @display: the display we got the pong from + * @event: the #XEvent which is a pong; we can tell which + * ping it corresponds to because it bears the + * same timestamp. + * * Process the pong (the response message) from the ping we sent * to the window. This involves removing the timeout, calling the * reply handler function, and freeing memory. - * - * \param display the display we got the pong from - * \param event the XEvent which is a pong; we can tell which - * ping it corresponds to because it bears the - * same timestamp. - * - * \ingroup pings */ static void process_pong_message (MetaDisplay *display, @@ -4468,18 +4469,17 @@ process_pong_message (MetaDisplay *display, } /** + * meta_display_window_has_pending_pings: + * @display: The #MetaDisplay of the window. + * @window: The #MetaWindow whose pings we want to know about. + * * Finds whether a window has any pings waiting on it. * - * \param display The MetaDisplay of the window. - * \param window The MetaWindow whose pings we want to know about. + * FIXME: This should probably be a method on windows, rather than displays + * for one of their windows. * - * \return True if there is at least one ping which has been sent - * to the window without getting a response; false otherwise. - * - * \bug This should probably be a method on windows, rather than displays - * for one of their windows. - * - * \ingroup pings + * Returns: %TRUE if there is at least one ping which has been sent + * to the window without getting a response; %FALSE otherwise. */ gboolean meta_display_window_has_pending_pings (MetaDisplay *display, diff --git a/src/core/main.c b/src/core/main.c index 2c00e8b99..fdf43578a 100644 --- a/src/core/main.c +++ b/src/core/main.c @@ -23,18 +23,19 @@ */ /** - * \file - * Program startup. + * SECTION:main + * @short_description: Program startup. + * * Functions which parse the command-line arguments, create the display, * kick everything off and then close down Mutter when it's time to go. - */ - -/** - * \mainpage + * + * + * * Mutter - a boring window manager for the adult in you * * Many window managers are like Marshmallow Froot Loops; Mutter - * is like Cheerios. + * is like Frosted Flakes: it's still plain old corn, but dusted + * with some sugar. * * The best way to get a handle on how the whole system fits together * is discussed in doc/code-overview.txt; if you're looking for functions @@ -77,12 +78,12 @@ #include #endif -/** +/* * The exit code we'll return to our parent process when we eventually die. */ static MetaExitCode meta_exit_code = META_EXIT_SUCCESS; -/** +/* * Handle on the main loop, so that we have an easy way of shutting Mutter * down. */ @@ -92,14 +93,15 @@ static void prefs_changed_callback (MetaPreference pref, gpointer data); /** + * log_handler: + * @log_domain: the domain the error occurred in (we ignore this) + * @log_level: the log level so that we can filter out less + * important messages + * @message: the message to log + * @user_data: arbitrary data (we ignore this) + * * Prints log messages. If Mutter was compiled with backtrace support, * also prints a backtrace (see meta_print_backtrace()). - * - * \param log_domain the domain the error occurred in (we ignore this) - * \param log_level the log level so that we can filter out less - * important messages - * \param message the message to log - * \param user_data arbitrary data (we ignore this) */ static void log_handler (const gchar *log_domain, @@ -112,10 +114,12 @@ log_handler (const gchar *log_domain, } /** + * meta_print_compilation_info: + * * Prints a list of which configure script options were used to * build this copy of Mutter. This is actually always called * on startup, but it's all no-op unless we're in verbose mode - * (see meta_set_verbose). + * (see meta_set_verbose()). */ static void meta_print_compilation_info (void) @@ -158,12 +162,14 @@ meta_print_compilation_info (void) } /** + * meta_print_self_identity: + * * Prints the version number, the current timestamp (not the * build date), the locale, the character encoding, and a list * of configure script options that were used to build this * copy of Mutter. This is actually always called * on startup, but it's all no-op unless we're in verbose mode - * (see meta_set_verbose). + * (see meta_set_verbose()). */ static void meta_print_self_identity (void) @@ -188,7 +194,7 @@ meta_print_self_identity (void) meta_print_compilation_info (); } -/** +/* * The set of possible options that can be set on Mutter's * command line. */ @@ -327,10 +333,12 @@ meta_clutter_init (void) } /** + * meta_select_display: + * * Selects which display Mutter should use. It first tries to use - * display_name as the display. If display_name is NULL then + * @display_name as the display. If @display_name is %NULL then * try to use the environment variable MUTTER_DISPLAY. If that - * also is NULL, use the default - :0.0 + * also is %NULL, use the default - :0.0 */ static void meta_select_display (gchar *display_name) @@ -560,13 +568,14 @@ meta_run (void) } /** + * meta_quit: + * @code: The success or failure code to return to the calling process. + * * Stops Mutter. This tells the event loop to stop processing; it is * rather dangerous to use this because this will leave the user with * no window manager. We generally do this only if, for example, the * session manager asks us to; we assume the session manager knows * what it's talking about. - * - * \param code The success or failure code to return to the calling process. */ void meta_quit (MetaExitCode code) @@ -579,13 +588,14 @@ meta_quit (MetaExitCode code) } /** + * prefs_changed_callback: + * @pref Which preference has changed + * @data Arbitrary data (which we ignore) + * * Called on pref changes. (One of several functions of its kind and purpose.) * - * \bug Why are these particular prefs handled in main.c and not others? - * Should they be? - * - * \param pref Which preference has changed - * \param data Arbitrary data (which we ignore) + * FIXME: Why are these particular prefs handled in main.c and not others? + * Should they be? */ static void prefs_changed_callback (MetaPreference pref, diff --git a/src/core/prefs.c b/src/core/prefs.c index e1dacf4ef..93c198786 100644 --- a/src/core/prefs.c +++ b/src/core/prefs.c @@ -165,36 +165,30 @@ typedef struct gboolean *target; } MetaBoolPreference; + +/** + * MetaStringPreference: + * @handler: (allow-none): A handler. Many of the string preferences + * aren't stored as strings and need parsing; others of them have + * default values which can't be solved in the general case. If you + * include a function pointer here, it will be called instead of writing + * the string value out to the target variable. + * The function will be passed to g_settings_get_mapped() and should + * return %TRUE if the mapping was successful and %FALSE otherwise. + * In the former case the function is expected to handle the result + * of the conversion itself and call queue_changed() appropriately; + * in particular the @result (out) parameter as returned by + * g_settings_get_mapped() will be ignored in all cases. + * This may be %NULL. If it is, see "target", below. + * @target: (allow-none): Where to write the incoming string. + * This must be %NULL if the handler is non-%NULL. + * If the incoming string is %NULL, no change will be made. + */ typedef struct { MetaBasePreference base; - - /** - * A handler. Many of the string preferences aren't stored as - * strings and need parsing; others of them have default values - * which can't be solved in the general case. If you include a - * function pointer here, it will be called instead of writing - * the string value out to the target variable. - * - * The function will be passed to g_settings_get_mapped() and should - * return %TRUE if the mapping was successful and %FALSE otherwise. - * In the former case the function is expected to handle the result - * of the conversion itself and call queue_changed() appropriately; - * in particular the @result (out) parameter as returned by - * g_settings_get_mapped() will be ignored in all cases. - * - * This may be NULL. If it is, see "target", below. - */ GSettingsGetMapping handler; - - /** - * Where to write the incoming string. - * - * This must be NULL if the handler is non-NULL. - * If the incoming string is NULL, no change will be made. - */ gchar **target; - } MetaStringPreference; typedef struct @@ -931,9 +925,9 @@ do_override (char *key, /** - * meta_prefs_override_preference_schema + * meta_prefs_override_preference_schema: * @key: the preference name - * @schema: new schema for preference %key + * @schema: new schema for preference @key * * Specify a schema whose keys are used to override the standard Metacity * keys. This might be used if a plugin expected a different value for @@ -1062,6 +1056,8 @@ bindings_changed (GSettings *settings, } /** + * maybe_give_disable_workaround_warning: + * * Special case: give a warning the first time disable_workarounds * is turned on. */ @@ -2004,7 +2000,8 @@ meta_prefs_remove_keybinding (const char *name) /** * meta_prefs_get_keybindings: - * Return: (element-type MetaKeyPref) (transfer container): + * + * Returns: (element-type MetaKeyPref) (transfer container): */ GList * meta_prefs_get_keybindings () diff --git a/src/core/screen.c b/src/core/screen.c index 5a36e439b..2df32b320 100644 --- a/src/core/screen.c +++ b/src/core/screen.c @@ -3454,9 +3454,10 @@ meta_screen_get_screen_number (MetaScreen *screen) /** * meta_screen_get_display: - * Retrieve the display associated with screen. * @screen: A #MetaScreen * + * Retrieve the display associated with screen. + * * Returns: (transfer none): Display */ MetaDisplay * diff --git a/src/core/stack.c b/src/core/stack.c index 47f51b2d0..5127d2852 100644 --- a/src/core/stack.c +++ b/src/core/stack.c @@ -1,7 +1,8 @@ /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */ /** - * \file stack.c Which windows cover which other windows + * SECTION:stack + * @short_description: Which windows cover which other windows */ /* @@ -799,6 +800,8 @@ apply_constraints (Constraint **constraints, } /** + * stack_do_window_deletions: + * * Go through "deleted" and take the matching windows * out of "windows". */ @@ -899,6 +902,8 @@ stack_do_window_additions (MetaStack *stack) } /** + * stack_do_relayer: + * * Update the layers that windows are in */ static void @@ -944,6 +949,8 @@ stack_do_relayer (MetaStack *stack) } /** + * stack_do_constrain: + * * Update stack_position and layer to reflect transiency * constraints */ @@ -976,6 +983,8 @@ stack_do_constrain (MetaStack *stack) } /** + * stack_do_resort: + * * Sort stack->sorted with layers having priority over stack_position. */ static void @@ -994,6 +1003,8 @@ stack_do_resort (MetaStack *stack) } /** + * stack_ensure_sorted: + * * Puts the stack into canonical form. * * Honour the removed and added lists of the stack, and then recalculate @@ -1013,6 +1024,8 @@ stack_ensure_sorted (MetaStack *stack) } /** + * raise_window_relative_to_managed_windows: + * * This function is used to avoid raising a window above popup * menus and other such things. * @@ -1113,6 +1126,8 @@ raise_window_relative_to_managed_windows (MetaScreen *screen, } /** + * stack_sync_to_server: + * * Order the windows on the X server to be the same as in our structure. * We do this using XRestackWindows if we don't know the previous order, * or XConfigureWindow on a few particular windows if we do and can figure diff --git a/src/core/stack.h b/src/core/stack.h index 4102cc609..fb54e2df0 100644 --- a/src/core/stack.h +++ b/src/core/stack.h @@ -1,23 +1,5 @@ /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */ -/** - * \file stack.h Which windows cover which other windows - * - * There are two factors that determine window position. - * - * One is window->stack_position, which is a unique integer - * indicating how windows are ordered with respect to one - * another. The ordering here transcends layers; it isn't changed - * as the window is moved among layers. This allows us to move several - * windows from one layer to another, while preserving the relative - * order of the moved windows. Also, it allows us to restore - * the stacking order from a saved session. - * - * However when actually stacking windows on the screen, the - * layer overrides the stack_position; windows are first sorted - * by layer, then by stack_position within each layer. - */ - /* * Copyright (C) 2001 Havoc Pennington * Copyright (C) 2005 Elijah Newren @@ -41,6 +23,25 @@ #ifndef META_STACK_H #define META_STACK_H +/** + * SECTION:stack + * @short_description: Which windows cover which other windows + * + * There are two factors that determine window position. + * + * One is window->stack_position, which is a unique integer + * indicating how windows are ordered with respect to one + * another. The ordering here transcends layers; it isn't changed + * as the window is moved among layers. This allows us to move several + * windows from one layer to another, while preserving the relative + * order of the moved windows. Also, it allows us to restore + * the stacking order from a saved session. + * + * However when actually stacking windows on the screen, the + * layer overrides the stack_position; windows are first sorted + * by layer, then by stack_position within each layer. + */ + #include "screen-private.h" /** @@ -123,192 +124,214 @@ struct _MetaStack }; /** + * meta_stack_new: + * @screen: The MetaScreen which will be the parent of this stack. + * * Creates and initialises a MetaStack. * - * \param screen The MetaScreen which will be the parent of this stack. - * \return The new screen. + * Returns: The new screen. */ MetaStack *meta_stack_new (MetaScreen *screen); /** - * Destroys and frees a MetaStack. + * meta_stack_free: + * @stack: The stack to destroy. * - * \param stack The stack to destroy. + * Destroys and frees a MetaStack. */ void meta_stack_free (MetaStack *stack); /** + * meta_stack_add: + * @stack: The stack to add it to + * @window: The window to add + * * Adds a window to the local stack. It is a fatal error to call this * function on a window which already exists on the stack of any screen. - * - * \param window The window to add - * \param stack The stack to add it to */ void meta_stack_add (MetaStack *stack, MetaWindow *window); /** + * meta_stack_remove: + * @stack: The stack to remove it from + * @window: The window to remove + * * Removes a window from the local stack. It is a fatal error to call this * function on a window which exists on the stack of any screen. - * - * \param window The window to remove - * \param stack The stack to remove it from */ void meta_stack_remove (MetaStack *stack, MetaWindow *window); /** + * meta_stack_update_layer: + * @stack: The stack to recalculate + * @window: Dummy parameter + * * Recalculates the correct layer for all windows in the stack, * and moves them about accordingly. * - * \param window Dummy parameter - * \param stack The stack to recalculate - * \bug What's with the dummy parameter? */ void meta_stack_update_layer (MetaStack *stack, MetaWindow *window); /** + * meta_stack_update_transient: + * @stack: The stack to recalculate + * @window: Dummy parameter + * * Recalculates the correct stacking order for all windows in the stack * according to their transience, and moves them about accordingly. * - * \param window Dummy parameter - * \param stack The stack to recalculate - * \bug What's with the dummy parameter? + * FIXME: What's with the dummy parameter? */ void meta_stack_update_transient (MetaStack *stack, MetaWindow *window); /** - * Move a window to the top of its layer. + * meta_stack_raise: + * @stack: The stack to modify. + * @window: The window that's making an ascension. + * (Amulet of Yendor not required.) * - * \param stack The stack to modify. - * \param window The window that's making an ascension. - * (Amulet of Yendor not required.) + * Move a window to the top of its layer. */ void meta_stack_raise (MetaStack *stack, MetaWindow *window); /** - * Move a window to the bottom of its layer. + * meta_stack_lower: + * @stack: The stack to modify. + * @window: The window that's on the way downwards. * - * \param stack The stack to modify. - * \param window The window that's on the way downwards. + * Move a window to the bottom of its layer. */ void meta_stack_lower (MetaStack *stack, MetaWindow *window); /** + * meta_stack_freeze: + * @stack: The stack to freeze. + * * Prevent syncing to server until the next call of meta_stack_thaw(), * so that we can carry out multiple operations in one go without having * everything halfway reflected on the X server. * * (Calls to meta_stack_freeze() nest, so that multiple calls to * meta_stack_freeze will require multiple calls to meta_stack_thaw().) - * - * \param stack The stack to freeze. */ void meta_stack_freeze (MetaStack *stack); /** + * meta_stack_thaw: + * @stack: The stack to thaw. + * * Undoes a meta_stack_freeze(), and processes anything which has become * necessary during the freeze. It is an error to call this function if * the stack has not been frozen. - * - * \param stack The stack to thaw. */ void meta_stack_thaw (MetaStack *stack); /** + * meta_stack_get_top: + * @stack: The stack to examine. + * * Finds the top window on the stack. * - * \param stack The stack to examine. - * \return The top window on the stack, or NULL in the vanishingly unlikely - * event that you have no windows on your screen whatsoever. + * Returns: The top window on the stack, or %NULL in the vanishingly unlikely + * event that you have no windows on your screen whatsoever. */ MetaWindow* meta_stack_get_top (MetaStack *stack); /** + * meta_stack_get_bottom: + * @stack: The stack to search + * * Finds the window at the bottom of the stack. Since that's pretty much * always the desktop, this isn't the most useful of functions, and nobody * actually calls it. We should probably get rid of it. - * - * \param stack The stack to search */ MetaWindow* meta_stack_get_bottom (MetaStack *stack); /** + * meta_stack_get_above: + * @stack: The stack to search. + * @window: The window to look above. + * @only_within_layer: If %TRUE, will return %NULL if @window is the + * top window in its layer. + * * Finds the window above a given window in the stack. * It is not an error to pass in a window which does not exist in - * the stack; the function will merely return NULL. + * the stack; the function will merely return %NULL. * - * \param stack The stack to search. - * \param window The window to look above. - * \param only_within_layer If true, will return NULL if "window" is the - * top window in its layer. - * \return NULL if there is no such window; - * the window above "window" otherwise. + * Returns: %NULL if there is no such window; + * the window above @window otherwise. */ MetaWindow* meta_stack_get_above (MetaStack *stack, MetaWindow *window, gboolean only_within_layer); /** + * meta_stack_get_below: + * @stack: The stack to search. + * @window: The window to look below. + * @only_within_layer: If %TRUE, will return %NULL if window is the + * bottom window in its layer. + * * Finds the window below a given window in the stack. * It is not an error to pass in a window which does not exist in - * the stack; the function will merely return NULL. + * the stack; the function will merely return %NULL. * - * \param stack The stack to search. - * \param window The window to look below. - * \param only_within_layer If true, will return NULL if "window" is the - * bottom window in its layer. - * \return NULL if there is no such window; - * the window below "window" otherwise. + * + * Returns: %NULL if there is no such window; + * the window below @window otherwise. */ MetaWindow* meta_stack_get_below (MetaStack *stack, MetaWindow *window, gboolean only_within_layer); /** - * Find the topmost, focusable, mapped, window in a stack. If you supply - * a window as "not_this_one", we won't return that one (presumably - * because it's going to be going away). But if you do supply "not_this_one" - * and we find its parent, we'll return that; and if "not_this_one" is in + * meta_stack_get_default_focus_window: + * @stack: The stack to search. + * @workspace: %NULL to search all workspaces; otherwise only windows + * from that workspace will be returned. + * @not_this_one: Window to ignore because it's being unfocussed or + * going away. + * + * Find the topmost, focusable, mapped, window in a stack. If you supply + * a window as @not_this_one, we won't return that one (presumably + * because it's going to be going away). But if you do supply @not_this_one + * and we find its parent, we'll return that; and if @not_this_one is in * a group, we'll return the top window of that group. * * Also, we are prejudiced against dock windows. Every kind of window, even * the desktop, will be returned in preference to a dock window. * - * \param stack The stack to search. - * \param workspace NULL to search all workspaces; otherwise only windows - * from that workspace will be returned. - * \param not_this_one Window to ignore because it's being unfocussed or - * going away. - * \return The window matching all these constraints or NULL if none does. - * - * \bug Never called! + * Returns: The window matching all these constraints or %NULL if none does. */ MetaWindow* meta_stack_get_default_focus_window (MetaStack *stack, MetaWorkspace *workspace, MetaWindow *not_this_one); /** + * meta_stack_get_default_focus_window_at_point: + * @stack: The stack to search. + * @workspace: %NULL to search all workspaces; otherwise only windows + * from that workspace will be returned. + * @not_this_one: Window to ignore because it's being unfocussed or + * going away. + * @root_x: The returned window must contain this point, + * unless it's a dock. + * @root_y: See root_x. + * * Find the topmost, focusable, mapped, window in a stack. If you supply - * a window as "not_this_one", we won't return that one (presumably - * because it's going to be going away). But if you do supply "not_this_one" - * and we find its parent, we'll return that; and if "not_this_one" is in + * a window as @not_this_one, we won't return that one (presumably + * because it's going to be going away). But if you do supply @not_this_one + * and we find its parent, we'll return that; and if @not_this_one is in * a group, we'll return the top window of that group. * * Also, we are prejudiced against dock windows. Every kind of window, even * the desktop, will be returned in preference to a dock window. * - * \param stack The stack to search. - * \param workspace NULL to search all workspaces; otherwise only windows - * from that workspace will be returned. - * \param not_this_one Window to ignore because it's being unfocussed or - * going away. - * \param root_x The returned window must contain this point, - * unless it's a dock. - * \param root_y See root_x. - * \return The window matching all these constraints or NULL if none does. + * Returns: The window matching all these constraints or %NULL if none does. */ MetaWindow* meta_stack_get_default_focus_window_at_point (MetaStack *stack, MetaWorkspace *workspace, @@ -317,18 +340,25 @@ MetaWindow* meta_stack_get_default_focus_window_at_point (MetaStack *stack, int root_y); /** + * meta_stack_list_windows: + * @stack: The stack to examine. + * @workspace: If not %NULL, only windows on this workspace will be + * returned; otherwise all windows in the stack will be + * returned. + * * Finds all the windows in the stack, in order. * - * \param stack The stack to examine. - * \param workspace If non-NULL, only windows on this workspace will be - * returned; otherwise all windows in the stack will be - * returned. - * \return A list of windows, in stacking order, honouring layers. + * Returns: A list of windows, in stacking order, honouring layers. */ GList* meta_stack_list_windows (MetaStack *stack, MetaWorkspace *workspace); /** + * meta_stack_windows_cmp: + * @stack: A stack containing both window_a and window_b + * @window_a: A window + * @window_b Another window + * * Comparison function for windows within a stack. This is not directly * suitable for use within a standard comparison routine, because it takes * an extra parameter; you will need to wrap it. @@ -339,9 +369,6 @@ GList* meta_stack_list_windows (MetaStack *stack, * * (FIXME: Apparently identical to compare_window_position(). Merge them.) * - * \param stack A stack containing both window_a and window_b - * \param window_a A window - * \param window_b Another window * \return -1 if window_a is below window_b, honouring layers; 1 if it's * above it; 0 if you passed in the same window twice! */ @@ -350,35 +377,40 @@ int meta_stack_windows_cmp (MetaStack *stack, MetaWindow *window_b); /** + * meta_window_set_stack_position: + * @window: The window which is moving. + * @position: Where it should move to (0 is the bottom). + * * Sets the position of a window within the stack. This will only move it * up or down within its layer. It is an error to attempt to move this * below position zero or above the last position in the stack (however, since * we don't provide a simple way to tell the number of windows in the stack, * this requirement may not be easy to fulfil). - * - * \param window The window which is moving. - * \param position Where it should move to (0 is the bottom). */ void meta_window_set_stack_position (MetaWindow *window, int position); /** + * meta_stack_get_positions: + * @stack: The stack to examine. + * * Returns the current stack state, allowing rudimentary transactions. * - * \param stack The stack to examine. - * \return An opaque GList representing the current stack sort order; - * it is the caller's responsibility to free it. - * Pass this to meta_stack_set_positions() later if you want to restore - * the state to where it was when you called this function. + * Returns: An opaque GList representing the current stack sort order; + * it is the caller's responsibility to free it. + * Pass this to meta_stack_set_positions() later if you want to restore + * the state to where it was when you called this function. */ GList* meta_stack_get_positions (MetaStack *stack); /** + * meta_stack_set_positions: + * @stack: The stack to roll back. + * @windows: The list returned from meta_stack_get_positions(). + * * Rolls back a transaction, given the list returned from * meta_stack_get_positions(). * - * \param stack The stack to roll back. - * \param windows The list returned from meta_stack_get_positions(). */ void meta_stack_set_positions (MetaStack *stack, GList *windows); diff --git a/src/core/window-props.c b/src/core/window-props.c index bd8262a22..1f5f04525 100644 --- a/src/core/window-props.c +++ b/src/core/window-props.c @@ -1,7 +1,8 @@ /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */ /** - * \file window-props.c MetaWindow property handling + * SECTION:window-props + * @short_description: #MetaWindow property handling * * A system which can inspect sets of properties of given windows * and take appropriate action given their values. @@ -389,11 +390,13 @@ reload_net_wm_user_time_window (MetaWindow *window, #define MAX_TITLE_LENGTH 512 /** - * Called by set_window_title and set_icon_title to set the value of - * *target to title. It required and atom is set, it will update the + * set_title_text: + * + * Called by set_window_title() and set_icon_title() to set the value of + * @target to @title. It required and @atom is set, it will update the * appropriate property. * - * Returns TRUE if a new title was set. + * Returns: %TRUE if a new title was set. */ static gboolean set_title_text (MetaWindow *window, @@ -1643,6 +1646,9 @@ RELOAD_STRING (gtk_menubar_object_path, "gtk-menubar-object-path") #undef RELOAD_STRING /** + * meta_display_init_window_prop_hooks: + * @display: The #MetaDisplay + * * Initialises the property hooks system. Each row in the table named "hooks" * represents an action to take when a property is found on a newly-created * window, or when a property changes its value. diff --git a/src/core/window-props.h b/src/core/window-props.h index 273dc7f42..3c433ee2d 100644 --- a/src/core/window-props.h +++ b/src/core/window-props.h @@ -1,7 +1,8 @@ /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */ /** - * \file window-props.h MetaWindow property handling + * SECTION:window-props + * @short_description: MetaWindow property handling * * A system which can inspect sets of properties of given windows * and take appropriate action given their values. @@ -35,12 +36,13 @@ #include "window-private.h" /** + * meta_window_reload_property: + * @window: The window. + * @property: A single X atom. + * * Requests the current values of a single property for a given * window from the server, and deals with it appropriately. * Does not return it to the caller (it's been dealt with!) - * - * \param window The window. - * \param property A single X atom. */ void meta_window_reload_property (MetaWindow *window, Atom property, @@ -48,13 +50,14 @@ void meta_window_reload_property (MetaWindow *window, /** + * meta_window_reload_properties: + * @window: The window. + * @properties: A pointer to a list of X atoms, "n_properties" long. + * @n_properties: The length of the properties list. + * * Requests the current values of a set of properties for a given * window from the server, and deals with them appropriately. * Does not return them to the caller (they've been dealt with!) - * - * \param window The window. - * \param properties A pointer to a list of X atoms, "n_properties" long. - * \param n_properties The length of the properties list. */ void meta_window_reload_properties (MetaWindow *window, const Atom *properties, @@ -62,14 +65,15 @@ void meta_window_reload_properties (MetaWindow *window, gboolean initial); /** + * meta_window_reload_property_from_xwindow: + * @window: A window on the same display as the one we're + * investigating (only used to find the display) + * @xwindow: The X handle for the window. + * @property: A single X atom. + * * Requests the current values of a single property for a given * window from the server, and deals with it appropriately. * Does not return it to the caller (it's been dealt with!) - * - * \param window A window on the same display as the one we're - * investigating (only used to find the display) - * \param xwindow The X handle for the window. - * \param property A single X atom. */ void meta_window_reload_property_from_xwindow (MetaWindow *window, @@ -78,15 +82,16 @@ void meta_window_reload_property_from_xwindow gboolean initial); /** + * meta_window_reload_properties_from_xwindow: + * @window: A window on the same display as the one we're + * investigating (only used to find the display) + * @xwindow: The X handle for the window. + * @properties: A pointer to a list of X atoms, "n_properties" long. + * @n_properties: The length of the properties list. + * * Requests the current values of a set of properties for a given * window from the server, and deals with them appropriately. * Does not return them to the caller (they've been dealt with!) - * - * \param window A window on the same display as the one we're - * investigating (only used to find the display) - * \param xwindow The X handle for the window. - * \param properties A pointer to a list of X atoms, "n_properties" long. - * \param n_properties The length of the properties list. */ void meta_window_reload_properties_from_xwindow (MetaWindow *window, @@ -96,41 +101,44 @@ void meta_window_reload_properties_from_xwindow gboolean initial); /** + * meta_window_load_initial_properties: + * @window: The window. + * * Requests the current values for standard properties for a given * window from the server, and deals with them appropriately. * Does not return them to the caller (they've been dealt with!) - * - * \param window The window. */ void meta_window_load_initial_properties (MetaWindow *window); /** + * meta_display_init_window_prop_hooks: + * @display: The display. + * * Initialises the hooks used for the reload_propert* functions * on a particular display, and stores a pointer to them in the * display. - * - * \param display The display. */ void meta_display_init_window_prop_hooks (MetaDisplay *display); /** + * meta_display_free_window_prop_hooks: + * @display: The display. * Frees the hooks used for the reload_propert* functions * for a particular display. - * - * \param display The display. */ void meta_display_free_window_prop_hooks (MetaDisplay *display); /** + * meta_set_normal_hints: + * @window: The window to set the size hints on. + * @hints: Either some X size hints, or NULL for default. + * * Sets the size hints for a window. This happens when a * WM_NORMAL_HINTS property is set on a window, but it is public * because the size hints are set to defaults when a window is * created. See * http://tronche.com/gui/x/icccm/sec-4.html#WM_NORMAL_HINTS * for the X details. - * - * \param window The window to set the size hints on. - * \param hints Either some X size hints, or NULL for default. */ void meta_set_normal_hints (MetaWindow *window, XSizeHints *hints); diff --git a/src/core/window.c b/src/core/window.c index 204bc0c65..b3a5633ec 100644 --- a/src/core/window.c +++ b/src/core/window.c @@ -3452,10 +3452,11 @@ meta_window_save_rect (MetaWindow *window) } /** + * force_save_user_window_placement: + * @window: Store current position of this window for future reference + * * Save the user_rect regardless of whether the window is maximized or * fullscreen. See save_user_window_placement() for most uses. - * - * \param window Store current position of this window for future reference */ static void force_save_user_window_placement (MetaWindow *window) @@ -3464,11 +3465,12 @@ force_save_user_window_placement (MetaWindow *window) } /** + * save_user_window_placement: + * @window: Store current position of this window for future reference + * * Save the user_rect, but only if the window is neither maximized nor * fullscreen, otherwise the window may snap back to those dimensions * (bug #461927). - * - * \param window Store current position of this window for future reference */ static void save_user_window_placement (MetaWindow *window) diff --git a/src/core/workspace.c b/src/core/workspace.c index eeb11c5b1..c858396d2 100644 --- a/src/core/workspace.c +++ b/src/core/workspace.c @@ -192,7 +192,7 @@ meta_workspace_new (MetaScreen *screen) return workspace; } -/** Foreach function for workspace_free_struts() */ +/* Foreach function for workspace_free_struts() */ static void free_this (gpointer candidate, gpointer dummy) { @@ -200,9 +200,10 @@ free_this (gpointer candidate, gpointer dummy) } /** - * Frees the combined struts list of a workspace. + * workspace_free_all_struts: + * @workspace: The workspace. * - * \param workspace The workspace. + * Frees the combined struts list of a workspace. */ static void workspace_free_all_struts (MetaWorkspace *workspace) @@ -216,9 +217,10 @@ workspace_free_all_struts (MetaWorkspace *workspace) } /** - * Frees the struts list set with meta_workspace_set_builtin_struts + * workspace_free_builtin_struts: + * @workspace: The workspace. * - * \param workspace The workspace. + * Frees the struts list set with meta_workspace_set_builtin_struts */ static void workspace_free_builtin_struts (MetaWorkspace *workspace) diff --git a/src/meta/common.h b/src/meta/common.h index 40d63dbde..7bf92f7cf 100644 --- a/src/meta/common.h +++ b/src/meta/common.h @@ -364,6 +364,7 @@ void meta_frame_borders_clear (MetaFrameBorders *self); (ycoord) < ((rect).y + (rect).height)) /** + * MetaStackLayer: * Layers a window can be in. * These MUST be in the order of stacking. */ diff --git a/src/meta/prefs.h b/src/meta/prefs.h index 3dc07c845..df17647dd 100644 --- a/src/meta/prefs.h +++ b/src/meta/prefs.h @@ -130,9 +130,10 @@ gboolean meta_prefs_get_compositing_manager (void); gboolean meta_prefs_get_force_fullscreen (void); /** - * Sets whether the compositor is turned on. + * meta_prefs_set_compositing_manager: + * @whether %TRUE to turn on, %FALSE to turn off. * - * \param whether TRUE to turn on, FALSE to turn off + * Sets whether the compositor is turned on. */ void meta_prefs_set_compositing_manager (gboolean whether); @@ -276,7 +277,7 @@ typedef struct MetaKeyBindingAction action; - /** + /* * A list of MetaKeyCombos. Each of them is bound to * this keypref. If one has keysym==modifiers==0, it is * ignored. diff --git a/src/meta/workspace.h b/src/meta/workspace.h index 12fe4bacd..33e1b6357 100644 --- a/src/meta/workspace.h +++ b/src/meta/workspace.h @@ -1,15 +1,5 @@ /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */ -/** - * \file workspace.h Workspaces - * - * A workspace is a set of windows which all live on the same - * screen. (You may also see the name "desktop" around the place, - * which is the EWMH's name for the same thing.) Only one workspace - * of a screen may be active at once; all windows on all other workspaces - * are unmapped. - */ - /* * Copyright (C) 2001 Havoc Pennington * Copyright (C) 2004, 2005 Elijah Newren @@ -33,6 +23,17 @@ #ifndef META_WORKSPACE_H #define META_WORKSPACE_H +/** + * SECTION:Workspaces + * @short_description:Workspaces + * + * A workspace is a set of windows which all live on the same + * screen. (You may also see the name "desktop" around the place, + * which is the EWMH's name for the same thing.) Only one workspace + * of a screen may be active at once; all windows on all other workspaces + * are unmapped. + */ + #include #include #include diff --git a/src/ui/tabpopup.c b/src/ui/tabpopup.c index c0868ee00..ac1029439 100644 --- a/src/ui/tabpopup.c +++ b/src/ui/tabpopup.c @@ -844,9 +844,12 @@ meta_select_workspace_class_init (MetaSelectWorkspaceClass *klass) } /** - * meta_convert_meta_to_wnck() converts a MetaWindow to a - * WnckWindowDisplayInfo window that is used to build a thumbnail of a - * workspace. + * meta_convert_meta_to_wnck: + * @window: the #MetaWindow + * @screen: the #MetaScreen the window is on + * + * Converts a #MetaWindow to a #WnckWindowDisplayInfo window + * that is used to build a thumbnail of a workspace. **/ static WnckWindowDisplayInfo meta_convert_meta_to_wnck (MetaWindow *window, MetaScreen *screen) diff --git a/src/ui/theme.c b/src/ui/theme.c index 604505fb7..d592ecd8a 100644 --- a/src/ui/theme.c +++ b/src/ui/theme.c @@ -22,7 +22,8 @@ */ /** - * \file theme.c Making Metacity look pretty + * SECTION:theme + * @short_description: Making Metacity look pretty * * The window decorations drawn by Metacity are described by files on disk * known internally as "themes" (externally as "window border themes" on @@ -30,26 +31,8 @@ * contains most of the code necessary to support themes; it does not * contain the XML parser, which is in theme-parser.c. * - * \bug This is a big file with lots of different subsystems, which might - * be better split out into separate files. - */ - -/** - * \defgroup tokenizer The theme expression tokenizer - * - * Themes can use a simple expression language to represent the values of - * things. This is the tokeniser used for that language. - * - * \bug We could remove almost all this code by using GScanner instead, - * but we would also have to find every expression in every existing theme - * we could and make sure the parse trees were the same. - */ - -/** - * \defgroup parser The theme expression parser - * - * Themes can use a simple expression language to represent the values of - * things. This is the parser used for that language. + * FIXME: This is a big file with lots of different subsystems, which might + * be better split out into separate files. */ #include @@ -89,7 +72,7 @@ static void hls_to_rgb (gdouble *h, gdouble *l, gdouble *s); -/** +/* * The current theme. (Themes are singleton.) */ static MetaTheme *meta_current_theme = NULL; @@ -185,9 +168,10 @@ color_composite (const GdkRGBA *bg, } /** - * Sets all the fields of a border to dummy values. + * init_border: + * @border: The border whose fields should be reset. * - * \param border The border whose fields should be reset. + * Sets all the fields of a border to dummy values. */ static void init_border (GtkBorder *border) @@ -240,9 +224,6 @@ meta_frame_layout_new (void) return layout; } -/** - * - */ static gboolean validate_border (const GtkBorder *border, const char **bad) @@ -262,17 +243,18 @@ validate_border (const GtkBorder *border, } /** + * validate_geometry_value: + * @val: The value to check + * @name: The name to use in the error message + * @error: (out): Set to an error if val was not initialised + * * Ensures that the theme supplied a particular dimension. When a - * MetaFrameLayout is created, all its integer fields are set to -1 + * #MetaFrameLayout is created, all its integer fields are set to -1 * by meta_frame_layout_new(). After an instance of this type * should have been initialised, this function checks that * a given field is not still at -1. It is never called directly, but - * rather via the CHECK_GEOMETRY_VALUE and CHECK_GEOMETRY_BORDER + * rather via the %CHECK_GEOMETRY_VALUE and %CHECK_GEOMETRY_BORDER * macros. - * - * \param val The value to check - * \param name The name to use in the error message - * \param[out] error Set to an error if val was not initialised */ static gboolean validate_geometry_value (int val, @@ -1640,10 +1622,12 @@ meta_color_spec_render (MetaColorSpec *spec, } /** + * op_name: + * @type: an operation, such as addition + * * Represents an operation as a string. * - * \param type an operation, such as addition - * \return a string, such as "+" + * Returns: a string, such as "+" */ static const char* op_name (PosOperatorType type) @@ -1672,12 +1656,14 @@ op_name (PosOperatorType type) } /** + * op_from_string: + * @p: a pointer into a string representing an operation; part of an + * expression somewhere, so not null-terminated + * @len: set to the length of the string found. Set to 0 if none is. + * * Parses a string and returns an operation. * - * \param p a pointer into a string representing an operation; part of an - * expression somewhere, so not null-terminated - * \param len set to the length of the string found. Set to 0 if none is. - * \return the operation found. If none was, returns POS_OP_NONE. + * Returns: the operation found. If none was, returns %POS_OP_NONE. */ static PosOperatorType op_from_string (const char *p, @@ -1728,11 +1714,12 @@ op_from_string (const char *p, } /** + * free_tokens: + * @tokens: an array of tokens to be freed + * @n_tokens: how many tokens are in the array. + * * Frees an array of tokens. All the tokens and their associated memory * will be freed. - * - * \param tokens an array of tokens to be freed - * \param n_tokens how many tokens are in the array. */ static void free_tokens (PosToken *tokens, @@ -1752,20 +1739,21 @@ free_tokens (PosToken *tokens, } /** + * parse_number: + * @p: a pointer into a string representing an operation; part of an + * expression somewhere, so not null-terminated + * @end_return: set to a pointer to the end of the number found; but + * not updated if no number was found at all + * @next: set to either an integer or a float token + * @err: (out): set to the problem if there was a problem + * * Tokenises a number in an expression. * - * \param p a pointer into a string representing an operation; part of an - * expression somewhere, so not null-terminated - * \param end_return set to a pointer to the end of the number found; but - * not updated if no number was found at all - * \param next set to either an integer or a float token - * \param[out] err set to the problem if there was a problem - * \return TRUE if a valid number was found, FALSE otherwise (and "err" will - * have been set) + * FIXME: The "while (*start)..." part: what's wrong with strchr-ish things? + * FIXME: The name is wrong: it doesn't parse anything. * - * \bug The "while (*start)..." part: what's wrong with strchr-ish things? - * \bug The name is wrong: it doesn't parse anything. - * \ingroup tokenizer + * Returns: %TRUE if a valid number was found, FALSE otherwise (and "err" will + * have been set) */ static gboolean parse_number (const char *p, @@ -1842,7 +1830,7 @@ parse_number (const char *p, return TRUE; } -/** +/* * Whether a variable can validly appear as part of the name of a variable. */ #define IS_VARIABLE_CHAR(c) (g_ascii_isalpha ((c)) || (c) == '_') @@ -1888,16 +1876,15 @@ debug_print_tokens (PosToken *tokens, #endif /** + * pos_tokenize: + * @expr: The expression + * @tokens_p: (out) The resulting tokens + * @n_tokens_p: (out): The number of resulting tokens + * @err: (out): set to the problem if there was a problem + * Tokenises an expression. * - * \param expr The expression - * \param[out] tokens_p The resulting tokens - * \param[out] n_tokens_p The number of resulting tokens - * \param[out] err set to the problem if there was a problem - * - * \return True if the expression was successfully tokenised; false otherwise. - * - * \ingroup tokenizer + * Returns: %TRUE if the expression was successfully tokenised; %FALSE otherwise. */ static gboolean pos_tokenize (const char *expr, @@ -2025,8 +2012,9 @@ pos_tokenize (const char *expr, } /** + * PosExprType: + * * The type of a PosExpr: either integer, double, or an operation. - * \ingroup parser */ typedef enum { @@ -2036,14 +2024,15 @@ typedef enum } PosExprType; /** + * PosExpr: + * * Type and value of an expression in a parsed sequence. We don't - * keep expressions in a tree; if this is of type POS_EXPR_OPERATOR, + * keep expressions in a tree; if this is of type %POS_EXPR_OPERATOR, * the arguments of the operator will be in the array positions * immediately preceding and following this operator; they cannot * themselves be operators. * - * \bug operator is char; it should really be of PosOperatorType. - * \ingroup parser + * FIXME: operator is #gchar; it should really be of #PosOperatorType. */ typedef struct { @@ -2334,29 +2323,29 @@ do_operations (PosExpr *exprs, } /** + * pos_eval_get_variable: + * @t: The token representing a variable + * @result: (out): The value of that variable; not set if the token did + * not represent a known variable + * @env: The environment within which t should be evaluated + * @err: (out): set to the problem if there was a problem + * * There is a predefined set of variables which can appear in an expression. * Here we take a token representing a variable, and return the current value * of that variable in a particular environment. * (The value is always an integer.) * * There are supposedly some circumstances in which this function can be - * called from outside Metacity, in which case env->theme will be NULL, and + * called from outside Metacity, in which case env->theme will be %NULL, and * therefore we can't use it to find out quark values, so we do the comparison - * using strcmp, which is slower. + * using strcmp(), which is slower. * - * \param t The token representing a variable - * \param[out] result The value of that variable; not set if the token did - * not represent a known variable - * \param env The environment within which t should be evaluated - * \param[out] err set to the problem if there was a problem + * FIXME: shouldn't @t be const? + * FIXME: we should perhaps consider some sort of lookup arrangement into an + * array; also, the duplication of code is unlovely; perhaps using glib + * string hashes instead of quarks would fix both problems? * - * \return true if we found the variable asked for, false if we didn't - * - * \bug shouldn't t be const? - * \bug we should perhaps consider some sort of lookup arrangement into an - * array; also, the duplication of code is unlovely; perhaps using glib - * string hashes instead of quarks would fix both problems? - * \ingroup parser + * Returns: %TRUE if we found the variable asked for, %FALSE if we didn't */ static gboolean pos_eval_get_variable (PosToken *t, @@ -2459,18 +2448,18 @@ pos_eval_get_variable (PosToken *t, } /** + * pos_eval_helper: + * @tokens: A list of tokens to evaluate. + * @n_tokens: How many tokens are in the list. + * @env: The environment context in which to evaluate the expression. + * @result: (out): The current value of the expression + * * Evaluates a sequence of tokens within a particular environment context, * and returns the current value. May recur if parantheses are found. * - * \param tokens A list of tokens to evaluate. - * \param n_tokens How many tokens are in the list. - * \param env The environment context in which to evaluate the expression. - * \param[out] result The current value of the expression - * - * \bug Yes, we really do reparse the expression every time it's evaluated. - * We should keep the parse tree around all the time and just - * run the new values through it. - * \ingroup parser + * FIXME: Yes, we really do reparse the expression every time it's evaluated. + * We should keep the parse tree around all the time and just + * run the new values through it. */ static gboolean pos_eval_helper (PosToken *tokens, @@ -2633,21 +2622,22 @@ pos_eval_helper (PosToken *tokens, * * so very not worth fooling with bison, yet so very painful by hand. */ + /** + * pos_eval: + * @spec: The expression to evaluate. + * @env: The environment context to evaluate the expression in. + * @val_p: (out): The integer value of the expression; if the expression + * is of type float, this will be rounded. If we return + * %FALSE because the expression is invalid, this will be + * zero. + * @err: (out): The error, if anything went wrong. + * * Evaluates an expression. * - * \param spec The expression to evaluate. - * \param env The environment context to evaluate the expression in. - * \param[out] val_p The integer value of the expression; if the expression - * is of type float, this will be rounded. If we return - * FALSE because the expression is invalid, this will be - * zero. - * \param[out] err The error, if anything went wrong. + * FIXME: Shouldn't @spec be const? * - * \return True if we evaluated the expression successfully; false otherwise. - * - * \bug Shouldn't spec be const? - * \ingroup parser + * Returns: %TRUE if we evaluated the expression successfully; %FALSE otherwise. */ static gboolean pos_eval (MetaDrawSpec *spec, @@ -4313,13 +4303,14 @@ meta_draw_op_list_contains (MetaDrawOpList *op_list, } /** + * meta_frame_style_new: + * @parent: The parent style. Data not filled in here will be + * looked for in the parent style, and in its parent + * style, and so on. + * * Constructor for a MetaFrameStyle. * - * \param parent The parent style. Data not filled in here will be - * looked for in the parent style, and in its parent - * style, and so on. - * - * \return The newly-constructed style. + * Returns: (transfer full): The newly-constructed style. */ MetaFrameStyle* meta_frame_style_new (MetaFrameStyle *parent) @@ -4341,10 +4332,10 @@ meta_frame_style_new (MetaFrameStyle *parent) } /** - * Increases the reference count of a frame style. - * If the style is NULL, this is a no-op. + * meta_frame_style_ref: + * @style: The style. * - * \param style The style. + * Increases the reference count of a frame style. */ void meta_frame_style_ref (MetaFrameStyle *style) @@ -5853,13 +5844,15 @@ meta_theme_define_color_constant (MetaTheme *theme, } /** + * meta_theme_lookup_color_constant: + * @theme: the theme containing the constant + * @name: the name of the constant + * @value: (out): the string representation of the colour, or %NULL if it + * doesn't exist + * * Looks up a colour constant. * - * \param theme the theme containing the constant - * \param name the name of the constant - * \param value [out] the string representation of the colour, or NULL if it - * doesn't exist - * \return TRUE if it exists, FALSE otherwise + * Returns: %TRUE if it exists, %FALSE otherwise */ gboolean meta_theme_lookup_color_constant (MetaTheme *theme, @@ -5910,11 +5903,13 @@ meta_gtk_widget_get_font_desc (GtkWidget *widget, } /** + * meta_pango_font_desc_get_text_height: + * @font_desc: the font + * @context: the context of the font + * * Returns the height of the letters in a particular font. * - * \param font_desc the font - * \param context the context of the font - * \return the height of the letters + * Returns: the height of the letters */ int meta_pango_font_desc_get_text_height (const PangoFontDescription *font_desc, @@ -6510,11 +6505,13 @@ meta_gtk_arrow_to_string (GtkArrowType arrow) } /** + * meta_image_fill_type_from_string: + * @str: a string representing a fill_type + * * Returns a fill_type from a string. The inverse of * meta_image_fill_type_to_string(). * - * \param str a string representing a fill_type - * \result the fill_type, or -1 if it represents no fill_type. + * Returns: the fill type, or -1 if it represents no fill type. */ MetaImageFillType meta_image_fill_type_from_string (const char *str) @@ -6528,11 +6525,13 @@ meta_image_fill_type_from_string (const char *str) } /** + * meta_image_fill_type_to_string: + * @fill_type: the fill type + * * Returns a string representation of a fill_type. The inverse of * meta_image_fill_type_from_string(). * - * \param fill_type the fill type - * \result a string representing that type + * Returns: a string representing that type */ const char* meta_image_fill_type_to_string (MetaImageFillType fill_type) @@ -6549,13 +6548,14 @@ meta_image_fill_type_to_string (MetaImageFillType fill_type) } /** + * gtk_style_shade: + * @a: the starting colour + * @b: (out): the resulting colour + * @k: amount to scale lightness and saturation by + * * Takes a colour "a", scales the lightness and saturation by a certain amount, * and sets "b" to the resulting colour. * gtkstyle.c cut-and-pastage. - * - * \param a the starting colour - * \param b [out] the resulting colour - * \param k amount to scale lightness and saturation by */ static void gtk_style_shade (GdkRGBA *a, @@ -6592,11 +6592,12 @@ gtk_style_shade (GdkRGBA *a, } /** - * Converts a red/green/blue triplet to a hue/lightness/saturation triplet. + * rgb_to_hls: + * @r: on input, red; on output, hue + * @g: on input, green; on output, lightness + * @b: on input, blue; on output, saturation * - * \param r on input, red; on output, hue - * \param g on input, green; on output, lightness - * \param b on input, blue; on output, saturation + * Converts a red/green/blue triplet to a hue/lightness/saturation triplet. */ static void rgb_to_hls (gdouble *r, @@ -6670,11 +6671,12 @@ rgb_to_hls (gdouble *r, } /** - * Converts a hue/lightness/saturation triplet to a red/green/blue triplet. + * hls_to_rgb: + * @h: on input, hue; on output, red + * @l: on input, lightness; on output, green + * @s: on input, saturation; on output, blue * - * \param h on input, hue; on output, red - * \param l on input, lightness; on output, green - * \param s on input, saturation; on output, blue + * Converts a hue/lightness/saturation triplet to a red/green/blue triplet. */ static void hls_to_rgb (gdouble *h, @@ -6966,12 +6968,14 @@ draw_bg_gradient_composite (const MetaTextureSpec *bg, #endif /** + * meta_theme_earliest_version_with_button: + * @type: the button type + * * Returns the earliest version of the theme format which required support * for a particular button. (For example, "shade" first appeared in v2, and * "close" in v1.) * - * \param type the button type - * \return the number of the theme format + * Returns: the number of the theme format */ guint meta_theme_earliest_version_with_button (MetaButtonType type)