r37753 - in /desktop/unstable/mutter/debian: changelog control patches/02_switch_to_gtk-doc_syntax.patch patches/series
ah at users.alioth.debian.org
ah at users.alioth.debian.org
Mon May 13 09:08:05 UTC 2013
Author: ah
Date: Mon May 13 09:08:05 2013
New Revision: 37753
URL: http://svn.debian.org/wsvn/pkg-gnome/?sc=1&rev=37753
Log:
Add patch to fix FTBFS with new gobject-introspection
Patch from upstream commit
https://git.gnome.org/browse/mutter/commit/?id=044d589
applies cleanly to mutter 3.4 as well.
See:
https://buildd.debian.org/status/fetch.php?pkg=mutter&arch=amd64&ver=3.4.1-5%2Bb1&stamp=1368400383
Added:
desktop/unstable/mutter/debian/patches/02_switch_to_gtk-doc_syntax.patch
Modified:
desktop/unstable/mutter/debian/changelog
desktop/unstable/mutter/debian/control
desktop/unstable/mutter/debian/patches/series
Modified: desktop/unstable/mutter/debian/changelog
URL: http://svn.debian.org/wsvn/pkg-gnome/desktop/unstable/mutter/debian/changelog?rev=37753&op=diff
==============================================================================
--- desktop/unstable/mutter/debian/changelog [utf-8] (original)
+++ desktop/unstable/mutter/debian/changelog [utf-8] Mon May 13 09:08:05 2013
@@ -1,3 +1,11 @@
+mutter (3.4.1-6) unstable; urgency=low
+
+ * Team upload
+ * Add debian/patches/02_switch_to_gtk-doc_syntax.patch:
+ - from upstream, fixes FTBFS with new gobject-introspection.
+
+ -- Andreas Henriksson <andreas at fatal.se> Mon, 13 May 2013 11:03:34 +0200
+
mutter (3.4.1-5) unstable; urgency=low
[ Rico Tzschichholz ]
Modified: desktop/unstable/mutter/debian/control
URL: http://svn.debian.org/wsvn/pkg-gnome/desktop/unstable/mutter/debian/control?rev=37753&op=diff
==============================================================================
--- desktop/unstable/mutter/debian/control [utf-8] (original)
+++ desktop/unstable/mutter/debian/control [utf-8] Mon May 13 09:08:05 2013
@@ -7,7 +7,7 @@
Section: x11
Priority: optional
Maintainer: Debian GNOME Maintainers <pkg-gnome-maintainers at lists.alioth.debian.org>
-Uploaders: Michael Biebl <biebl at debian.org>, Sjoerd Simons <sjoerd at debian.org>
+Uploaders: Andreas Henriksson <andreas at fatal.se>, Michael Biebl <biebl at debian.org>, Sjoerd Simons <sjoerd at debian.org>
Build-Depends: cdbs (>= 0.4.90),
debhelper (>= 8),
dh-autoreconf,
Added: desktop/unstable/mutter/debian/patches/02_switch_to_gtk-doc_syntax.patch
URL: http://svn.debian.org/wsvn/pkg-gnome/desktop/unstable/mutter/debian/patches/02_switch_to_gtk-doc_syntax.patch?rev=37753&op=file
==============================================================================
--- desktop/unstable/mutter/debian/patches/02_switch_to_gtk-doc_syntax.patch (added)
+++ desktop/unstable/mutter/debian/patches/02_switch_to_gtk-doc_syntax.patch [utf-8] Mon May 13 09:08:05 2013
@@ -1,0 +1,2207 @@
+From 044d58951e4d72f387377ee75f647d9dc63462f1 Mon Sep 17 00:00:00 2001
+From: Jasper St. Pierre <jstpierre at mecheye.net>
+Date: Wed, 02 Nov 2011 15:34:45 +0000
+Subject: Switch to gtk-doc syntax
+
+https://bugzilla.gnome.org/show_bug.cgi?id=673752
+---
+diff --git a/src/compositor/meta-plugin.c b/src/compositor/meta-plugin.c
+index 475f877..f687c0b 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 dbb2188..4f48c6f 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 50f059f..e9ba84b 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:
+- * <http://bugzilla.gnome.org/show_bug.cgi?id=99886>.
+- */
+-
+ /*
+ * Copyright (C) 2002 Sun Microsystems Inc.
+ *
+diff --git a/src/core/display.c b/src/core/display.c
+index 676cd56..c4e93c3 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;
+
+ /**
+- * Returns whether X synchronisation is currently enabled.
++ * meta_is_syncing:
+ *
+- * \return true if we must wait for events whenever we send X requests;
+- * false otherwise.
++ * Returns whether X synchronisation is currently enabled.
+ *
+- * \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.)
+- *
+- * \bug This should probably be a method on windows, rather than displays
+- * for one of their windows.
++ * FIXME: 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,
+ }
+
+ /**
+- * Finds whether a window has any pings waiting on it.
++ * meta_display_window_has_pending_pings:
++ * @display: The #MetaDisplay of the window.
++ * @window: The #MetaWindow whose pings we want to know about.
+ *
+- * \param display The MetaDisplay of the window.
+- * \param window The MetaWindow whose pings we want to know about.
+- *
+- * \return True if there is at least one ping which has been sent
+- * to the window without getting a response; false otherwise.
++ * Finds whether a window has any pings waiting on it.
+ *
+- * \bug This should probably be a method on windows, rather than displays
+- * for one of their windows.
++ * FIXME: 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 2c00e8b..fdf4357 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 <girepository.h>
+ #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)
+ }
+
+ /**
+- * Called on pref changes. (One of several functions of its kind and purpose.)
++ * prefs_changed_callback:
++ * @pref Which preference has changed
++ * @data Arbitrary data (which we ignore)
+ *
+- * \bug Why are these particular prefs handled in main.c and not others?
+- * Should they be?
++ * Called on pref changes. (One of several functions of its kind and purpose.)
+ *
+- * \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 e1dacf4..93c1987 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 5a36e43..2df32b3 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 47f51b2..5127d28 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 4102cc6..fb54e2d 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.
+- *
+- * \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.
++ * the stack; the function will merely return %NULL.
++ *
++ * 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.
+- *
+- * \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.
++ * the stack; the function will merely return %NULL.
++ *
++ *
++ * 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 bd8262a..1f5f045 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 273dc7f..3c433ee 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 204bc0c..b3a5633 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 eeb11c5..c858396 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 40d63db..7bf92f7 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 3dc07c8..df17647 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 12fe4ba..33e1b63 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 <meta/types.h>
+ #include <meta/boxes.h>
+ #include <meta/screen.h>
+diff --git a/src/ui/tabpopup.c b/src/ui/tabpopup.c
+index c0868ee..ac10294 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 604505f..d592ecd 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 <config.h>
+@@ -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,
+ }
+
+ /**
+- * Tokenises a number in an expression.
+- *
+- * \param p a pointer into a string representing an operation; part of an
++ * parse_number:
++ * @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
++ * @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)
++ * @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.
++ *
++ * 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.
+- *
+- * \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
++ * using strcmp(), which is slower.
+ *
+- * \return true if we found the variable asked for, false if we didn't
++ * 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?
+ *
+- * \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.
+ */
++
+ /**
+- * Evaluates an expression.
++ * 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.
+ *
+- * \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.
++ * Evaluates an expression.
+ *
+- * \return True if we evaluated the expression successfully; false otherwise.
++ * FIXME: Shouldn't @spec be const?
+ *
+- * \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,
+ }
+
+ /**
+- * Constructor for a MetaFrameStyle.
++ * 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.
+ *
+- * \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.
++ * Constructor for a MetaFrameStyle.
+ *
+- * \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)
+--
+cgit v0.9.1
Modified: desktop/unstable/mutter/debian/patches/series
URL: http://svn.debian.org/wsvn/pkg-gnome/desktop/unstable/mutter/debian/patches/series?rev=37753&op=diff
==============================================================================
--- desktop/unstable/mutter/debian/patches/series [utf-8] (original)
+++ desktop/unstable/mutter/debian/patches/series [utf-8] Mon May 13 09:08:05 2013
@@ -1,2 +1,3 @@
00_meta_window_move_frame-fix-crash-when-frame-is-NULL.patch
01_Wcast-align.patch
+02_switch_to_gtk-doc_syntax.patch
More information about the pkg-gnome-commits
mailing list