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