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