diff --git a/src/compositor/cogl-utils.c b/src/compositor/cogl-utils.c
index 0494463a8..7d4bb3a07 100644
--- a/src/compositor/cogl-utils.c
+++ b/src/compositor/cogl-utils.c
@@ -26,10 +26,10 @@
 
 /**
  * meta_create_color_texture_4ub:
- * @red:
- * @green:
- * @blue:
- * @alpha:
+ * @red: red component
+ * @green: green component
+ * @blue: blue component
+ * @alpha: alpha component
  * @flags: Optional flags for the texture, or %COGL_TEXTURE_NONE;
  *   %COGL_TEXTURE_NO_SLICING is useful if the texture will be
  *   repeated to create a constant color fill, since hardware
diff --git a/src/compositor/compositor.c b/src/compositor/compositor.c
index d6aa536f9..413ee4f36 100644
--- a/src/compositor/compositor.c
+++ b/src/compositor/compositor.c
@@ -838,6 +838,9 @@ maybe_spoof_guard_window_event_as_stage_event (MetaCompScreen *info,
 
 /**
  * meta_compositor_process_event: (skip)
+ * @compositor: 
+ * @event: 
+ * @window: 
  *
  */
 gboolean
@@ -1414,6 +1417,7 @@ on_shadow_factory_changed (MetaShadowFactory *factory,
 
 /**
  * meta_compositor_new: (skip)
+ * @display:
  *
  */
 MetaCompositor *
@@ -1458,6 +1462,7 @@ meta_compositor_new (MetaDisplay *display)
 
 /**
  * meta_get_overlay_window: (skip)
+ * @screen: a #MetaScreen
  *
  */
 Window
diff --git a/src/compositor/meta-window-actor.c b/src/compositor/meta-window-actor.c
index f54b87f86..58b141e1f 100644
--- a/src/compositor/meta-window-actor.c
+++ b/src/compositor/meta-window-actor.c
@@ -786,6 +786,7 @@ meta_window_actor_has_shadow (MetaWindowActor *self)
 
 /**
  * meta_window_actor_get_x_window: (skip)
+ * @self: a #MetaWindowActor
  *
  */
 Window
@@ -799,6 +800,7 @@ meta_window_actor_get_x_window (MetaWindowActor *self)
 
 /**
  * meta_window_actor_get_meta_window:
+ * @self: a #MetaWindowActor
  *
  * Gets the #MetaWindow object that the the #MetaWindowActor is displaying
  *
@@ -812,6 +814,7 @@ meta_window_actor_get_meta_window (MetaWindowActor *self)
 
 /**
  * meta_window_actor_get_texture:
+ * @self: a #MetaWindowActor
  *
  * Gets the ClutterActor that is used to display the contents of the window
  *
@@ -825,6 +828,7 @@ meta_window_actor_get_texture (MetaWindowActor *self)
 
 /**
  * meta_window_actor_is_destroyed:
+ * @self: a #MetaWindowActor
  *
  * Gets whether the X window that the actor was displaying has been destroyed
  *
diff --git a/src/core/bell.c b/src/core/bell.c
index 4f48c6f94..9d7dc7af9 100644
--- a/src/core/bell.c
+++ b/src/core/bell.c
@@ -22,8 +22,8 @@
  * 02111-1307, USA.
  */
 
-/**
- * SECTION:Bell
+/*
+ * SECTION:bell
  * @short_description: Ring the bell or flash the screen
  *
  * Sometimes, X programs "ring the bell", whatever that means. Mutter lets
@@ -52,7 +52,9 @@
 #include <config.h>
 #include "bell.h"
 #include "screen-private.h"
+#include "window-private.h"
 #include <meta/prefs.h>
+#include <meta/compositor.h>
 #ifdef HAVE_LIBCANBERRA
 #include <canberra-gtk.h>
 #endif
diff --git a/src/core/bell.h b/src/core/bell.h
index e9ba84bd2..0065be9d4 100644
--- a/src/core/bell.h
+++ b/src/core/bell.h
@@ -28,30 +28,35 @@
 
 #ifdef HAVE_XKB
 /**
+ * meta_bell_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; in fact, this is our response
  * to any kind of bell request, but we set it up so that we only get
  * notified about visual bells, and X deals with audible ones.
  *
  * 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
  */
 void meta_bell_notify (MetaDisplay *display, XkbAnyEvent *xkb_ev);
 #endif
 
 /**
+ * meta_bell_set_audible:
+ * @display: The display we're configuring
+ * @audible: True for an audible bell, false for a visual bell
+ *
  * Turns the bell to audible or visual. This tells X what to do, but
  * not Mutter; you will need to set the "visual bell" pref for that.
  *
  * If the configure script found we had no XKB, this is a no-op.
- *
- * \param display  The display we're configuring
- * \param audible  True for an audible bell, false for a visual bell
  */
 void meta_bell_set_audible (MetaDisplay *display, gboolean audible);
 
 /**
+ * meta_bell_init:
+ * @display: The display which is opening
+ *
  * Initialises the bell subsystem. This involves intialising
  * XKB (which, despite being a keyboard extension, is the
  * place to look for bell notifications), then asking it
@@ -64,8 +69,6 @@ void meta_bell_set_audible (MetaDisplay *display, gboolean audible);
  * we will have HAVE_XKB undefined, which will cause this
  * function to be a no-op.
  *
- * \param display  The display which is opening
- *
  * \bug There is a line of code that's never run that tells
  * XKB to reset the bell status after we quit. Bill H said
  * (<http://bugzilla.gnome.org/show_bug.cgi?id=99886#c12>)
@@ -75,9 +78,10 @@ void meta_bell_set_audible (MetaDisplay *display, gboolean audible);
 gboolean meta_bell_init (MetaDisplay *display);
 
 /**
- * Shuts down the bell subsystem.
+ * meta_bell_shutdown:
+ * @display: The display which is closing
  *
- * \param display  The display which is closing
+ * Shuts down the bell subsystem.
  *
  * \bug This is never called! If we had XkbSetAutoResetControls
  * enabled in meta_bell_init(), this wouldn't be a problem, but
@@ -86,11 +90,12 @@ gboolean meta_bell_init (MetaDisplay *display);
 void 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/display.c b/src/core/display.c
index c409744c1..5c0de6257 100644
--- a/src/core/display.c
+++ b/src/core/display.c
@@ -24,7 +24,7 @@
  * 02111-1307, USA.
  */
 
-/**
+/*
  * SECTION:MetaDisplay
  * @short_description: Handles operations on an X display.
  *
@@ -83,7 +83,7 @@
          g == META_GRAB_OP_KEYBOARD_ESCAPING_DOCK   ||  \
          g == META_GRAB_OP_KEYBOARD_ESCAPING_GROUP)
 
-/**
+/*
  * SECTION:pings
  *
  * Sometimes we want to see whether a window is responding,
@@ -1132,6 +1132,7 @@ meta_display_close (MetaDisplay *display,
 /**
  * meta_display_screen_for_root:
  * @display: a #MetaDisplay
+ * @xroot: a X window
  *
  * Return the #MetaScreen corresponding to a specified X root window ID.
  *
@@ -3638,7 +3639,7 @@ meta_display_notify_window_created (MetaDisplay  *display,
  * @display: A #MetaDisplay
  * @xwindow: An X11 window
  *
- * Returns %TRUE iff window is one of mutter's internal "no focus" windows
+ * Returns: %TRUE iff window is one of mutter's internal "no focus" windows
  * (there is one per screen) which will have the focus when there is no
  * actual client window focused.
  */
@@ -4098,6 +4099,8 @@ meta_display_end_grab_op (MetaDisplay *display,
 
 /**
  * meta_display_get_grab_op:
+ * @display: The #MetaDisplay that the window is on
+
  * Gets the current grab operation, if any.
  *
  * Return value: the current grab operation, or %META_GRAB_OP_NONE if
@@ -4469,6 +4472,7 @@ meta_is_syncing (void)
 
 /**
  * meta_set_syncing:
+ * @setting: whether to turn syncing on or off
  *
  * A handy way to turn on synchronisation on or off for every display.
  */
@@ -5689,6 +5693,7 @@ meta_display_get_compositor_version (MetaDisplay *display,
 
 /**
  * meta_display_get_xinput_opcode: (skip)
+ * @display: a #MetaDisplay
  *
  */
 int
@@ -5701,7 +5706,7 @@ meta_display_get_xinput_opcode (MetaDisplay *display)
  * meta_display_supports_extended_barriers:
  * @display: a #MetaDisplay
  *
- * Returns whether the X server supports extended barrier
+ * Returns: whether the X server supports extended barrier
  * features as defined in version 2.3 of the XInput 2
  * specification.
  *
@@ -5716,6 +5721,7 @@ meta_display_supports_extended_barriers (MetaDisplay *display)
 
 /**
  * meta_display_get_xdisplay: (skip)
+ * @display: a #MetaDisplay
  *
  */
 Display *
@@ -5726,6 +5732,7 @@ meta_display_get_xdisplay (MetaDisplay *display)
 
 /**
  * meta_display_get_compositor: (skip)
+ * @display: a #MetaDisplay
  *
  */
 MetaCompositor *
diff --git a/src/core/group.c b/src/core/group.c
index f6b839a42..54f42f61f 100644
--- a/src/core/group.c
+++ b/src/core/group.c
@@ -106,6 +106,7 @@ meta_group_unref (MetaGroup *group)
 
 /**
  * meta_window_get_group: (skip)
+ * @window: a #MetaWindow
  *
  */
 MetaGroup*
@@ -204,6 +205,8 @@ meta_window_shutdown_group (MetaWindow *window)
 
 /**
  * meta_display_lookup_group: (skip)
+ * @display: a #MetaDisplay
+ * @group_leader: a X window
  *
  */
 MetaGroup*
@@ -279,6 +282,8 @@ meta_group_get_startup_id (MetaGroup *group)
 
 /**
  * meta_group_property_notify: (skip)
+ * @group: a #MetaGroup
+ * @event: a X event
  *
  */
 gboolean
diff --git a/src/core/keybindings.c b/src/core/keybindings.c
index 480837944..6b9db0eb5 100644
--- a/src/core/keybindings.c
+++ b/src/core/keybindings.c
@@ -3861,6 +3861,11 @@ meta_keybindings_set_custom_handler (const gchar        *name,
 
 /**
  * meta_keybindings_switch_window: (skip)
+ * @display: a #MetaDisplay
+ * @screen: a #MetaScreen
+ * @event_window: a #MetaWindow
+ * @event: a #XIDeviceEvent
+ * @binding: a #MetaKeyBinding
  *
  */
 void
diff --git a/src/core/main.c b/src/core/main.c
index 60709182e..7054d97e8 100644
--- a/src/core/main.c
+++ b/src/core/main.c
@@ -581,8 +581,8 @@ meta_quit (MetaExitCode code)
 
 /**
  * prefs_changed_callback:
- * @pref  Which preference has changed
- * @data  Arbitrary data (which we ignore)
+ * @pref:  Which preference has changed
+ * @data:  Arbitrary data (which we ignore)
  *
  * Called on pref changes. (One of several functions of its kind and purpose.)
  *
diff --git a/src/core/prefs.c b/src/core/prefs.c
index 363bccd64..13ace779a 100644
--- a/src/core/prefs.c
+++ b/src/core/prefs.c
@@ -700,6 +700,8 @@ handle_preference_update_int (GSettings *settings,
 
 /**
  * meta_prefs_add_listener: (skip)
+ * @func: a #MetaPrefsChangedFunc
+ * @user_data: data passed to the function
  *
  */
 void
@@ -717,6 +719,8 @@ meta_prefs_add_listener (MetaPrefsChangedFunc func,
 
 /**
  * meta_prefs_remove_listener: (skip)
+ * @func: a #MetaPrefsChangedFunc
+ * @user_data: data passed to the function
  *
  */
 void
diff --git a/src/core/screen.c b/src/core/screen.c
index 1266196ed..48f020281 100644
--- a/src/core/screen.c
+++ b/src/core/screen.c
@@ -3484,6 +3484,7 @@ meta_screen_get_display (MetaScreen *screen)
 
 /**
  * meta_screen_get_xroot: (skip)
+ * @screen: A #MetaScreen
  *
  */
 Window
@@ -3514,6 +3515,7 @@ meta_screen_get_size (MetaScreen *screen,
 
 /**
  * meta_screen_get_compositor_data: (skip)
+ * @screen: A #MetaScreen
  *
  */
 gpointer
@@ -3582,6 +3584,7 @@ meta_screen_get_active_workspace_index (MetaScreen *screen)
 
 /**
  * meta_screen_get_active_workspace:
+ * @screen: A #MetaScreen
  *
  * Returns: (transfer none): The current workspace
  */
diff --git a/src/core/stack-tracker.c b/src/core/stack-tracker.c
index d45a52bed..2c0c04655 100644
--- a/src/core/stack-tracker.c
+++ b/src/core/stack-tracker.c
@@ -1,5 +1,20 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
+/*
+ * SECTION:stack-tracker
+ * @short_description: Track stacking order for compositor
+ *
+ * #MetaStackTracker maintains the most accurate view we have at a
+ * given point of time of the ordering of the children of the root
+ * window (including override-redirect windows.) This is used to order
+ * the windows when the compositor draws them.
+ *
+ * By contrast, #MetaStack is responsible for keeping track of how we
+ * think that windows *should* be ordered.  For windows we manage
+ * (non-override-redirect windows), the two stacking orders will be
+ * the same.
+ */
+
 /*
  * Copyright (C) 2009 Red Hat, Inc.
  *
@@ -616,7 +631,7 @@ meta_stack_tracker_configure_event (MetaStackTracker    *tracker,
  * @windows: location to store list of windows, or %NULL
  * @n_windows: location to store count of windows, or %NULL
  *
- * Returns the most current view we have of the stacking order
+ * @windows will contain the most current view we have of the stacking order
  * of the children of the root window. The returned array contains
  * everything: InputOnly windows, override-redirect windows,
  * hidden windows, etc. Some of these will correspond to MetaWindow
diff --git a/src/core/stack.c b/src/core/stack.c
index 1d481f9cb..c5fd30f63 100644
--- a/src/core/stack.c
+++ b/src/core/stack.c
@@ -1,6 +1,6 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/**
+/*
  * SECTION:stack
  * @short_description: Which windows cover which other windows
  */
diff --git a/src/core/util.c b/src/core/util.c
index a8da0d2dd..8f10bbbc7 100644
--- a/src/core/util.c
+++ b/src/core/util.c
@@ -225,6 +225,7 @@ utf8_fputs (const char *str,
 
 /**
  * meta_free_gslist_and_elements: (skip)
+ * @list_to_deep_free: list to deep free
  *
  */
 void
@@ -599,6 +600,16 @@ append_argument (GPtrArray  *args,
 
 /**
  * meta_show_dialog: (skip)
+ * @type: type of dialog
+ * @message: message
+ * @timeout: timeout
+ * @display: display
+ * @ok_text: text for Ok button
+ * @cancel_text: text for Cancel button
+ * @icon_name: icon name
+ * @transient_for: window XID of parent
+ * @columns: columns
+ * @entries: entries
  *
  */
 GPid
diff --git a/src/core/window-props.c b/src/core/window-props.c
index b4225631f..0b9d7ea85 100644
--- a/src/core/window-props.c
+++ b/src/core/window-props.c
@@ -1,6 +1,6 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/**
+/*
  * SECTION:window-props
  * @short_description: #MetaWindow property handling
  *
diff --git a/src/core/window.c b/src/core/window.c
index 46e276dcf..e915aa10e 100644
--- a/src/core/window.c
+++ b/src/core/window.c
@@ -2130,7 +2130,7 @@ set_net_wm_state (MetaWindow *window)
  * @window: a #MetaWindow
  * @workspace: a #MetaWorkspace
  *
- * Returns whether @window is displayed on @workspace, or whether it
+ * Returns: whether @window is displayed on @workspace, or whether it
  * will be displayed on all workspaces.
  */
 gboolean
@@ -3629,6 +3629,7 @@ meta_window_maximize (MetaWindow        *window,
 
 /**
  * meta_window_get_maximized:
+ * @window: a #MetaWindow
  *
  * Gets the current maximization state of the window, as combination
  * of the %META_MAXIMIZE_HORIZONTAL and %META_MAXIMIZE_VERTICAL flags;
@@ -3644,6 +3645,7 @@ meta_window_get_maximized (MetaWindow *window)
 
 /**
  * meta_window_is_fullscreen:
+ * @window: a #MetaWindow
  *
  * Return value: %TRUE if the window is currently fullscreen
  */
@@ -3690,6 +3692,7 @@ meta_window_get_all_monitors (MetaWindow *window, gsize *length)
 
 /**
  * meta_window_is_screen_sized:
+ * @window: A #MetaWindow
  *
  * Return value: %TRUE if the window is occupies the
  *               the whole screen (all monitors).
@@ -3741,6 +3744,7 @@ meta_window_is_monitor_sized (MetaWindow *window)
 
 /**
  * meta_window_is_on_primary_monitor:
+ * @window: a #MetaWindow
  *
  * Return value: %TRUE if the window is on the primary monitor
  */
@@ -3752,6 +3756,7 @@ meta_window_is_on_primary_monitor (MetaWindow *window)
 
 /**
  * meta_window_requested_bypass_compositor:
+ * @window: a #MetaWindow
  *
  * Return value: %TRUE if the window requested to bypass the compositor
  */
@@ -3763,6 +3768,7 @@ meta_window_requested_bypass_compositor (MetaWindow *window)
 
 /**
  * meta_window_requested_dont_bypass_compositor:
+ * @window: a #MetaWindow
  *
  * Return value: %TRUE if the window requested to opt out of unredirecting
  */
@@ -10333,6 +10339,7 @@ meta_window_stack_just_below (MetaWindow *window,
 
 /**
  * meta_window_get_user_time:
+ * @window: a #MetaWindow
  *
  * The user time represents a timestamp for the last time the user
  * interacted with this window.  Note this property is only available
@@ -10501,6 +10508,7 @@ meta_window_unset_demands_attention (MetaWindow *window)
 
 /**
  * meta_window_get_frame: (skip)
+ * @window: a #MetaWindow
  *
  */
 MetaFrame *
@@ -10541,7 +10549,7 @@ meta_window_is_shaded (MetaWindow *window)
  * meta_window_is_override_redirect:
  * @window: A #MetaWindow
  *
- * Returns if this window isn't managed by mutter; it will
+ * Returns: %TRUE if this window isn't managed by mutter; it will
  * control its own positioning and mutter won't draw decorations
  * among other things.  In X terminology this is "override redirect".
  */
@@ -10609,6 +10617,7 @@ meta_window_get_display (MetaWindow *window)
 
 /**
  * meta_window_get_xwindow: (skip)
+ * @window: a #MetaWindow
  *
  */
 Window
@@ -10819,7 +10828,7 @@ meta_window_get_role (MetaWindow *window)
  * meta_window_get_title:
  * @window: a #MetaWindow
  *
- * Returns the current title of the window.
+ * Returns: the current title of the window.
  */
 const char *
 meta_window_get_title (MetaWindow *window)
@@ -11046,6 +11055,7 @@ meta_window_get_frame_type (MetaWindow *window)
 
 /**
  * meta_window_get_frame_bounds:
+ * @window: a #MetaWindow
  *
  * Gets a region representing the outer bounds of the window's frame.
  *
@@ -11083,6 +11093,7 @@ meta_window_is_attached_dialog (MetaWindow *window)
 
 /**
  * meta_window_get_tile_match:
+ * @window: a #MetaWindow
  *
  * Returns the matching tiled window on the same monitor as @window. This is
  * the topmost tiled window in a complementary tile mode that is:
diff --git a/src/meta/atomnames.h b/src/meta/atomnames.h
index d05182677..d262071b8 100644
--- a/src/meta/atomnames.h
+++ b/src/meta/atomnames.h
@@ -23,7 +23,7 @@
  * 02111-1307, USA.
  */
 
-/**
+/*
  * \file atomnames.h  A list of atom names.
  *
  * This is a list of the names of all the X atoms that Mutter uses.
diff --git a/src/meta/barrier.h b/src/meta/barrier.h
index a5f6e0a84..d7b1666c7 100644
--- a/src/meta/barrier.h
+++ b/src/meta/barrier.h
@@ -22,6 +22,13 @@ typedef struct _MetaBarrierPrivate MetaBarrierPrivate;
 
 typedef struct _MetaBarrierEvent   MetaBarrierEvent;
 
+/**
+ * MetaBarrier:
+ *
+ * The <structname>MetaBarrier</structname> structure contains
+ * only private data and should be accessed using the provided API
+ *
+ **/
 struct _MetaBarrier
 {
   GObject parent;
@@ -29,8 +36,15 @@ struct _MetaBarrier
   MetaBarrierPrivate *priv;
 };
 
+/**
+ * MetaBarrierClass:
+ *
+ * The <structname>MetaBarrierClass</structname> structure contains only
+ * private data.
+ */
 struct _MetaBarrierClass
 {
+  /*< private >*/
   GObjectClass parent_class;
 };
 
@@ -41,6 +55,14 @@ void meta_barrier_destroy (MetaBarrier *barrier);
 void meta_barrier_release (MetaBarrier      *barrier,
                            MetaBarrierEvent *event);
 
+/**
+ * MetaBarrierDirection:
+ * @META_BARRIER_DIRECTION_POSITIVE_X: Positive direction in the X axis
+ * @META_BARRIER_DIRECTION_POSITIVE_Y: Positive direction in the Y axis
+ * @META_BARRIER_DIRECTION_NEGATIVE_X: Negative direction in the X axis
+ * @META_BARRIER_DIRECTION_NEGATIVE_Y: Negative direction in the Y axis
+ */
+
 /* Keep in sync with XFixes */
 typedef enum {
   META_BARRIER_DIRECTION_POSITIVE_X = 1 << 0,
diff --git a/src/meta/boxes.h b/src/meta/boxes.h
index 4503c3070..0adcfcb37 100644
--- a/src/meta/boxes.h
+++ b/src/meta/boxes.h
@@ -29,6 +29,13 @@
 
 #define META_TYPE_RECTANGLE            (meta_rectangle_get_type ())
 
+/**
+ * MetaRectangle:
+ * @x: X coordinate of the top-left corner
+ * @y: Y coordinate of the top-left corner
+ * @width: Width of the rectangle
+ * @height: Height of the rectangle
+ */
 typedef struct _MetaRectangle MetaRectangle;
 struct _MetaRectangle
 {
@@ -38,6 +45,11 @@ struct _MetaRectangle
   int height;
 };
 
+/**
+ * MetaStrut:
+ * @rect: #MetaRectangle the #MetaStrut is on
+ * @side: #MetaSide the #MetaStrut is on
+ */
 typedef struct _MetaStrut MetaStrut;
 struct _MetaStrut
 {
@@ -45,6 +57,12 @@ struct _MetaStrut
   MetaSide side;
 };
 
+/**
+ * MetaEdgeType:
+ * @META_EDGE_WINDOW: Whether the edge belongs to a window
+ * @META_EDGE_MONITOR: Whether the edge belongs to a monitor
+ * @META_EDGE_SCREEN: Whether the edge belongs to a screen
+ */
 typedef enum
 {
   META_EDGE_WINDOW,
@@ -52,6 +70,12 @@ typedef enum
   META_EDGE_SCREEN
 } MetaEdgeType;
 
+/**
+ * MetaEdge:
+ * @rect: #MetaRectangle with the bounds of the edge
+ * @side_type: Side
+ * @edge_type: To what belongs the edge
+ */
 typedef struct _MetaEdge MetaEdge;
 struct _MetaEdge
 {
diff --git a/src/meta/common.h b/src/meta/common.h
index 5526d094e..8af3e078a 100644
--- a/src/meta/common.h
+++ b/src/meta/common.h
@@ -41,6 +41,26 @@
 
 typedef struct _MetaResizePopup MetaResizePopup;
 
+/**
+ * MetaFrameFlags:
+ * @META_FRAME_ALLOWS_DELETE: frame allows delete
+ * @META_FRAME_ALLOWS_MENU: frame allows menu
+ * @META_FRAME_ALLOWS_MINIMIZE: frame allows minimize
+ * @META_FRAME_ALLOWS_MAXIMIZE: frame allows maximize
+ * @META_FRAME_ALLOWS_VERTICAL_RESIZE: frame allows vertical resize
+ * @META_FRAME_ALLOWS_HORIZONTAL_RESIZE: frame allows horizontal resize
+ * @META_FRAME_HAS_FOCUS: frame has focus
+ * @META_FRAME_SHADED: frame is shaded
+ * @META_FRAME_STUCK: frame is stuck
+ * @META_FRAME_MAXIMIZED: frame is maximized
+ * @META_FRAME_ALLOWS_SHADE: frame allows shade
+ * @META_FRAME_ALLOWS_MOVE: frame allows move
+ * @META_FRAME_FULLSCREEN: frame allows fullscreen
+ * @META_FRAME_IS_FLASHING: frame is flashing
+ * @META_FRAME_ABOVE: frame is above
+ * @META_FRAME_TILED_LEFT: frame is tiled to the left
+ * @META_FRAME_TILED_RIGHT: frame is tiled to the right
+ */
 typedef enum
 {
   META_FRAME_ALLOWS_DELETE            = 1 << 0,
@@ -62,6 +82,28 @@ typedef enum
   META_FRAME_TILED_RIGHT              = 1 << 16
 } MetaFrameFlags;
 
+/**
+ * MetaMenuOp:
+ * @META_MENU_OP_NONE: No menu operation
+ * @META_MENU_OP_DELETE: Menu operation delete
+ * @META_MENU_OP_MINIMIZE: Menu operation minimize
+ * @META_MENU_OP_UNMAXIMIZE: Menu operation unmaximize
+ * @META_MENU_OP_MAXIMIZE: Menu operation maximize
+ * @META_MENU_OP_UNSHADE: Menu operation unshade
+ * @META_MENU_OP_SHADE: Menu operation shade
+ * @META_MENU_OP_UNSTICK: Menu operation unstick
+ * @META_MENU_OP_STICK: Menu operation stick
+ * @META_MENU_OP_WORKSPACES: Menu operation workspaces
+ * @META_MENU_OP_MOVE: Menu operation move
+ * @META_MENU_OP_RESIZE: Menu operation resize
+ * @META_MENU_OP_ABOVE: Menu operation above
+ * @META_MENU_OP_UNABOVE: Menu operation unabove
+ * @META_MENU_OP_MOVE_LEFT: Menu operation left
+ * @META_MENU_OP_MOVE_RIGHT: Menu operation right
+ * @META_MENU_OP_MOVE_UP: Menu operation up
+ * @META_MENU_OP_MOVE_DOWN: Menu operation down
+ * @META_MENU_OP_RECOVER: Menu operation recover
+ */
 typedef enum
 {
   META_MENU_OP_NONE        = 0,
@@ -95,6 +137,49 @@ typedef void (* MetaWindowMenuFunc) (MetaWindowMenu *menu,
                                      int             workspace,
                                      gpointer        user_data);
 
+/**
+ * MetaGrabOp:
+ * @META_GRAB_OP_NONE: None
+ * @META_GRAB_OP_MOVING: Moving with pointer
+ * @META_GRAB_OP_RESIZING_SE: Resizing SE with pointer
+ * @META_GRAB_OP_RESIZING_S: Resizing S with pointer
+ * @META_GRAB_OP_RESIZING_SW: Resizing SW with pointer
+ * @META_GRAB_OP_RESIZING_N: Resizing N with pointer
+ * @META_GRAB_OP_RESIZING_NE: Resizing NE with pointer
+ * @META_GRAB_OP_RESIZING_NW: Resizing NW with pointer
+ * @META_GRAB_OP_RESIZING_W: Resizing W with pointer
+ * @META_GRAB_OP_RESIZING_E: Resizing E with pointer
+ * @META_GRAB_OP_KEYBOARD_MOVING: Moving with keyboard
+ * @META_GRAB_OP_KEYBOARD_RESIZING_UNKNOWN: Resizing with keyboard
+ * @META_GRAB_OP_KEYBOARD_RESIZING_S: Resizing S with keyboard
+ * @META_GRAB_OP_KEYBOARD_RESIZING_N: Resizing N with keyboard
+ * @META_GRAB_OP_KEYBOARD_RESIZING_W: Resizing W with keyboard
+ * @META_GRAB_OP_KEYBOARD_RESIZING_E: Resizing E with keyboard
+ * @META_GRAB_OP_KEYBOARD_RESIZING_SE: Resizing SE with keyboard
+ * @META_GRAB_OP_KEYBOARD_RESIZING_NE: Resizing NE with keyboard
+ * @META_GRAB_OP_KEYBOARD_RESIZING_SW: Resizing SW with keyboard
+ * @META_GRAB_OP_KEYBOARD_RESIZING_NW: Resizing NS with keyboard
+ * @META_GRAB_OP_KEYBOARD_TABBING_NORMAL: Tabbing
+ * @META_GRAB_OP_KEYBOARD_TABBING_DOCK: Tabbing through docks
+ * @META_GRAB_OP_KEYBOARD_ESCAPING_NORMAL: Escaping
+ * @META_GRAB_OP_KEYBOARD_ESCAPING_DOCK: Escaping through docks
+ * @META_GRAB_OP_KEYBOARD_ESCAPING_GROUP: Escaping through groups
+ * @META_GRAB_OP_KEYBOARD_TABBING_GROUP: Tabbing through groups
+ * @META_GRAB_OP_KEYBOARD_WORKSPACE_SWITCHING: Switch to another workspace
+ * @META_GRAB_OP_CLICKING_MINIMIZE: Clicked minimize button
+ * @META_GRAB_OP_CLICKING_MAXIMIZE: Clicked maximize button
+ * @META_GRAB_OP_CLICKING_UNMAXIMIZE: Clicked unmaximize button
+ * @META_GRAB_OP_CLICKING_DELETE: Clicked delete button
+ * @META_GRAB_OP_CLICKING_MENU: Clicked on menu
+ * @META_GRAB_OP_CLICKING_SHADE: Clicked shade button
+ * @META_GRAB_OP_CLICKING_UNSHADE: Clicked unshade button
+ * @META_GRAB_OP_CLICKING_ABOVE: Clicked above button
+ * @META_GRAB_OP_CLICKING_UNABOVE: Clicked unabove button
+ * @META_GRAB_OP_CLICKING_STICK: Clicked stick button
+ * @META_GRAB_OP_CLICKING_UNSTICK: Clicked unstick button
+ * @META_GRAB_OP_COMPOSITOR: Compositor asked for grab
+ */
+
 /* when changing this enum, there are various switch statements
  * you have to update
  */
@@ -157,6 +242,20 @@ typedef enum
   META_GRAB_OP_COMPOSITOR
 } MetaGrabOp;
 
+/**
+ * MetaCursor:
+ * @META_CURSOR_DEFAULT: Default cursor
+ * @META_CURSOR_NORTH_RESIZE: Resize northern edge cursor
+ * @META_CURSOR_SOUTH_RESIZE: Resize southern edge cursor
+ * @META_CURSOR_WEST_RESIZE: Resize western edge cursor
+ * @META_CURSOR_EAST_RESIZE: Resize eastern edge cursor
+ * @META_CURSOR_SE_RESIZE: Resize south-eastern corner cursor
+ * @META_CURSOR_SW_RESIZE: Resize south-western corner cursor
+ * @META_CURSOR_NE_RESIZE: Resize north-eastern corner cursor
+ * @META_CURSOR_NW_RESIZE: Resize north-western corner cursor
+ * @META_CURSOR_MOVE_OR_RESIZE_WINDOW: Move or resize cursor
+ * @META_CURSOR_BUSY: Busy cursor
+ */
 typedef enum
 {
   META_CURSOR_DEFAULT,
@@ -173,6 +272,17 @@ typedef enum
 
 } MetaCursor;
 
+/**
+ * MetaFrameType:
+ * @META_FRAME_TYPE_NORMAL: Normal frame
+ * @META_FRAME_TYPE_DIALOG: Dialog frame
+ * @META_FRAME_TYPE_MODAL_DIALOG: Modal dialog frame
+ * @META_FRAME_TYPE_UTILITY: Utility frame
+ * @META_FRAME_TYPE_MENU: Menu frame
+ * @META_FRAME_TYPE_BORDER: Border frame
+ * @META_FRAME_TYPE_ATTACHED: Attached frame
+ * @META_FRAME_TYPE_LAST: Marks the end of the #MetaFrameType enumeration
+ */
 typedef enum
 {
   META_FRAME_TYPE_NORMAL,
@@ -185,6 +295,19 @@ typedef enum
   META_FRAME_TYPE_LAST
 } MetaFrameType;
 
+/**
+ * MetaVirtualModifier:
+ * @META_VIRTUAL_SHIFT_MASK: Shift mask
+ * @META_VIRTUAL_CONTROL_MASK: Control mask
+ * @META_VIRTUAL_ALT_MASK: Alt mask
+ * @META_VIRTUAL_META_MASK: Meta mask
+ * @META_VIRTUAL_SUPER_MASK: Super mask
+ * @META_VIRTUAL_HYPER_MASK: Hyper mask
+ * @META_VIRTUAL_MOD2_MASK: Mod2 mask
+ * @META_VIRTUAL_MOD3_MASK: Mod3 mask
+ * @META_VIRTUAL_MOD4_MASK: Mod4 mask
+ * @META_VIRTUAL_MOD5_MASK: Mod5 mask
+ */
 typedef enum
 {
   /* Create gratuitous divergence from regular
@@ -202,6 +325,18 @@ typedef enum
   META_VIRTUAL_MOD5_MASK     = 1 << 14
 } MetaVirtualModifier;
 
+/**
+ * MetaDirection:
+ * @META_DIRECTION_LEFT: Left
+ * @META_DIRECTION_RIGHT: Right
+ * @META_DIRECTION_TOP: Top
+ * @META_DIRECTION_BOTTOM: Bottom
+ * @META_DIRECTION_UP: Up
+ * @META_DIRECTION_DOWN: Down
+ * @META_DIRECTION_HORIZONTAL: Horizontal
+ * @META_DIRECTION_VERTICAL: Vertical
+ */
+
 /* Relative directions or sides seem to come up all over the place... */
 /* FIXME: Replace
  *   screen.[ch]:MetaScreenDirection,
@@ -224,6 +359,18 @@ typedef enum
   META_DIRECTION_VERTICAL   = META_DIRECTION_UP   | META_DIRECTION_DOWN,
 } MetaDirection;
 
+/**
+ * MetaMotionDirection:
+ * @META_MOTION_UP: Upwards motion
+ * @META_MOTION_DOWN: Downwards motion
+ * @META_MOTION_LEFT: Motion to the left
+ * @META_MOTION_RIGHT: Motion to the right
+ * @META_MOTION_UP_LEFT: Motion up and to the left
+ * @META_MOTION_UP_RIGHT: Motion up and to the right
+ * @META_MOTION_DOWN_LEFT: Motion down and to the left
+ * @META_MOTION_DOWN_RIGHT: Motion down and to the right
+ */
+
 /* Negative to avoid conflicting with real workspace
  * numbers
  */
@@ -240,6 +387,14 @@ typedef enum
   META_MOTION_DOWN_RIGHT = -8
 } MetaMotionDirection;
 
+/**
+ * MetaSide:
+ * @META_SIDE_LEFT: Left side
+ * @META_SIDE_RIGHT: Right side
+ * @META_SIDE_TOP: Top side
+ * @META_SIDE_BOTTOM: Bottom side
+ */
+
 /* Sometimes we want to talk about sides instead of directions; note
  * that the values must be as follows or meta_window_update_struts()
  * won't work. Using these values also is a safety blanket since
@@ -253,7 +408,21 @@ typedef enum
   META_SIDE_BOTTOM          = META_DIRECTION_BOTTOM
 } MetaSide;
 
-/* Function a window button can have.  Note, you can't add stuff here
+/**
+ * MetaButtonFunction:
+ * @META_BUTTON_FUNCTION_MENU: Menu
+ * @META_BUTTON_FUNCTION_MINIMIZE: Minimize
+ * @META_BUTTON_FUNCTION_MAXIMIZE: Maximize
+ * @META_BUTTON_FUNCTION_CLOSE: Close
+ * @META_BUTTON_FUNCTION_SHADE: Shade
+ * @META_BUTTON_FUNCTION_ABOVE: Above
+ * @META_BUTTON_FUNCTION_STICK: Stick
+ * @META_BUTTON_FUNCTION_UNSHADE: Unshade
+ * @META_BUTTON_FUNCTION_UNABOVE: Unabove
+ * @META_BUTTON_FUNCTION_UNSTICK: Unstick
+ * @META_BUTTON_FUNCTION_LAST: Marks the end of the #MetaButtonFunction enumeration
+ *
+ * Function a window button can have.  Note, you can't add stuff here
  * without extending the theme format to draw a new function and
  * breaking all existing themes.
  */
@@ -294,6 +463,12 @@ struct _MetaButtonLayout
   gboolean right_buttons_has_spacer[MAX_BUTTONS_PER_CORNER];
 };
 
+/**
+ * MetaFrameBorders:
+ * @visible: inner visible portion of frame border
+ * @invisible: outer invisible portion of frame border
+ * @total: sum of the two borders above
+ */
 typedef struct _MetaFrameBorders MetaFrameBorders;
 struct _MetaFrameBorders
 {
@@ -379,6 +554,16 @@ void meta_frame_borders_clear (MetaFrameBorders *self);
 
 /**
  * MetaStackLayer:
+ * @META_LAYER_DESKTOP: Desktop layer
+ * @META_LAYER_BOTTOM: Bottom layer
+ * @META_LAYER_NORMAL: Normal layer
+ * @META_LAYER_TOP: Top layer
+ * @META_LAYER_DOCK: Dock layer
+ * @META_LAYER_FULLSCREEN: Fullscreen layer
+ * @META_LAYER_FOCUSED_WINDOW: Focused window layer
+ * @META_LAYER_OVERRIDE_REDIRECT: Override-redirect layer
+ * @META_LAYER_LAST: Marks the end of the #MetaStackLayer enumeration
+ *
  * Layers a window can be in.
  * These MUST be in the order of stacking.
  */
diff --git a/src/meta/display.h b/src/meta/display.h
index 3b6d4cbb5..d4c3aaeb5 100644
--- a/src/meta/display.h
+++ b/src/meta/display.h
@@ -29,6 +29,13 @@
 #include <meta/prefs.h>
 #include <meta/common.h>
 
+/**
+ * MetaTabList:
+ * @META_TAB_LIST_NORMAL: Normal windows
+ * @META_TAB_LIST_DOCKS: Dock windows
+ * @META_TAB_LIST_GROUP: Groups
+ * @META_TAB_LIST_NORMAL_ALL: All windows
+ */
 typedef enum
 {
   META_TAB_LIST_NORMAL,
@@ -37,6 +44,11 @@ typedef enum
   META_TAB_LIST_NORMAL_ALL
 } MetaTabList;
 
+/**
+ * MetaTabShowType:
+ * @META_TAB_SHOW_ICON: Show icon (Alt-Tab mode)
+ * @META_TAB_SHOW_INSTANTLY: Show instantly (Alt-Esc mode)
+ */
 typedef enum
 {
   META_TAB_SHOW_ICON,      /* Alt-Tab mode */
diff --git a/src/meta/gradient.h b/src/meta/gradient.h
index 5e9db8a04..bcf5521b2 100644
--- a/src/meta/gradient.h
+++ b/src/meta/gradient.h
@@ -27,6 +27,14 @@
 #include <gdk-pixbuf/gdk-pixbuf.h>
 #include <gdk/gdk.h>
 
+/**
+ * MetaGradientType:
+ * @META_GRADIENT_VERTICAL: Vertical gradient
+ * @META_GRADIENT_HORIZONTAL: Horizontal gradient
+ * @META_GRADIENT_DIAGONAL: Diagonal gradient
+ * @META_GRADIENT_LAST: Marks the end of the #MetaGradientType enumeration
+ *
+ */
 typedef enum
 {
   META_GRADIENT_VERTICAL,
diff --git a/src/meta/main.h b/src/meta/main.h
index 256987e82..dd4e7f1d9 100644
--- a/src/meta/main.h
+++ b/src/meta/main.h
@@ -35,6 +35,11 @@ gboolean        meta_get_replace_current_wm (void);  /* Actually defined in util
 void            meta_set_wm_name              (const char *wm_name);
 void            meta_set_gnome_wm_keybindings (const char *wm_keybindings);
 
+/**
+ * MetaExitCode:
+ * @META_EXIT_SUCCESS: Success
+ * @META_EXIT_ERROR: Error
+ */
 typedef enum
 {
   META_EXIT_SUCCESS,
diff --git a/src/meta/meta-background-actor.h b/src/meta/meta-background-actor.h
index 69ec37764..96fe1c636 100644
--- a/src/meta/meta-background-actor.h
+++ b/src/meta/meta-background-actor.h
@@ -52,6 +52,7 @@ typedef struct _MetaBackgroundActorPrivate MetaBackgroundActorPrivate;
 
 struct _MetaBackgroundActorClass
 {
+  /*< private >*/
   ClutterActorClass parent_class;
 };
 
diff --git a/src/meta/meta-background-group.h b/src/meta/meta-background-group.h
index 60dd4906d..edd3e3127 100644
--- a/src/meta/meta-background-group.h
+++ b/src/meta/meta-background-group.h
@@ -30,11 +30,13 @@ typedef struct _MetaBackgroundGroupPrivate MetaBackgroundGroupPrivate;
 
 struct _MetaBackgroundGroupClass
 {
+  /*< private >*/
   ClutterActorClass parent_class;
 };
 
 struct _MetaBackgroundGroup
 {
+  /*< private >*/
   ClutterActor parent;
 
   MetaBackgroundGroupPrivate *priv;
diff --git a/src/meta/meta-background.h b/src/meta/meta-background.h
index bd73e9226..62d60ca5b 100644
--- a/src/meta/meta-background.h
+++ b/src/meta/meta-background.h
@@ -52,6 +52,11 @@ typedef struct _MetaBackgroundPrivate MetaBackgroundPrivate;
 
 /**
  * MetaBackgroundEffects:
+ * @META_BACKGROUND_EFFECTS_NONE: No effect
+ * @META_BACKGROUND_EFFECTS_DESATURATE: Desaturate
+ * @META_BACKGROUND_EFFECTS_BLUR: Blur
+ * @META_BACKGROUND_EFFECTS_VIGNETTE: Vignette
+ *
  * Which effects to enable on the background
  */
 
@@ -65,11 +70,13 @@ typedef enum
 
 struct _MetaBackgroundClass
 {
+  /*< private >*/
   GObjectClass parent_class;
 };
 
 struct _MetaBackground
 {
+  /*< private >*/
   GObject parent;
 
   MetaBackgroundPrivate *priv;
diff --git a/src/meta/meta-plugin.h b/src/meta/meta-plugin.h
index 9a3d0a375..3ea3435b1 100644
--- a/src/meta/meta-plugin.h
+++ b/src/meta/meta-plugin.h
@@ -52,15 +52,59 @@ struct _MetaPlugin
   MetaPluginPrivate *priv;
 };
 
+/**
+ * MetaPluginClass:
+ * @start: virtual function called when the compositor starts managing a screen
+ * @minimize: virtual function called when a window is minimized
+ * @maximize: virtual function called when a window is maximized
+ * @unmaximize: virtual function called when a window is unmaximized
+ * @map: virtual function called when a window is mapped
+ * @destroy: virtual function called when a window is destroyed
+ * @switch_workspace: virtual function called when the user switches to another
+ * workspace
+ * @kill_window_effects: virtual function called when the effects on a window
+ * need to be killed prematurely; the plugin must call the completed() callback
+ * as if the effect terminated naturally
+ * @kill_switch_workspace: virtual function called when the workspace-switching
+ * effect needs to be killed prematurely
+ * @xevent_filter: virtual function called when handling each event
+ * @keybinding_filter: virtual function called when handling each keybinding
+ * @plugin_info: virtual function that returns information about the
+ * #MetaPlugin
+ */
 struct _MetaPluginClass
 {
+  /*< private >*/
   GObjectClass parent_class;
 
+  /*< public >*/
+
+  /**
+   * MetaPluginClass::start:
+   *
+   * Virtual function called when the compositor starts managing a screen
+   */
   void (*start)            (MetaPlugin         *plugin);
 
+  /**
+   * MetaPluginClass::minimize:
+   * @actor: a #MetaWindowActor
+   *
+   * Virtual function called when the window represented by @actor is minimized.
+   */
   void (*minimize)         (MetaPlugin         *plugin,
                             MetaWindowActor    *actor);
 
+  /**
+   * MetaPluginClass::maximize:
+   * @actor: a #MetaWindowActor
+   * @x: target X coordinate
+   * @y: target Y coordinate
+   * @width: target width
+   * @height: target height
+   *
+   * Virtual function called when the window represented by @actor is maximized.
+   */
   void (*maximize)         (MetaPlugin         *plugin,
                             MetaWindowActor    *actor,
                             gint                x,
@@ -68,6 +112,16 @@ struct _MetaPluginClass
                             gint                width,
                             gint                height);
 
+  /**
+   * MetaPluginClass::unmaximize:
+   * @actor: a #MetaWindowActor
+   * @x: target X coordinate
+   * @y: target Y coordinate
+   * @width: target width
+   * @height: target height
+   *
+   * Virtual function called when the window represented by @actor is unmaximized.
+   */
   void (*unmaximize)       (MetaPlugin         *plugin,
                             MetaWindowActor    *actor,
                             gint                x,
@@ -75,42 +129,101 @@ struct _MetaPluginClass
                             gint                width,
                             gint                height);
 
+  /**
+   * MetaPluginClass::map:
+   * @actor: a #MetaWindowActor
+   *
+   * Virtual function called when the window represented by @actor is mapped.
+   */
   void (*map)              (MetaPlugin         *plugin,
                             MetaWindowActor    *actor);
 
+  /**
+   * MetaPluginClass::destroy:
+   * @actor: a #MetaWindowActor
+   *
+   * Virtual function called when the window represented by @actor is destroyed.
+   */
   void (*destroy)          (MetaPlugin         *plugin,
                             MetaWindowActor    *actor);
 
+  /**
+   * MetaPluginClass::switch_workspace:
+   * @from: origin workspace
+   * @to: destination workspace
+   * @direction: a #MetaMotionDirection
+   *
+   * Virtual function called when the window represented by @actor is destroyed.
+   */
   void (*switch_workspace) (MetaPlugin         *plugin,
                             gint                from,
                             gint                to,
                             MetaMotionDirection direction);
 
-  /*
-   * Called if an effects should be killed prematurely; the plugin must
-   * call the completed() callback as if the effect terminated naturally.
+
+  /**
+   * MetaPluginClass::kill_window_effects:
+   * @actor: a #MetaWindowActor
+   *
+   * Virtual function called when the effects on @actor need to be killed
+   * prematurely; the plugin must call the completed() callback as if the effect
+   * terminated naturally.
    */
   void (*kill_window_effects)      (MetaPlugin      *plugin,
                                     MetaWindowActor *actor);
 
+  /**
+   * MetaPluginClass::kill_switch_workspace:
+   *
+   * Virtual function called when the workspace-switching effect needs to be
+   * killed prematurely.
+   */
   void (*kill_switch_workspace)    (MetaPlugin     *plugin);
 
-  /* General XEvent filter. This is fired *before* meta itself handles
-   * an event. Return TRUE to block any further processing.
-   */
   /**
    * MetaPluginClass::xevent_filter:
    * @event: (type xlib.XEvent):
+   *
+   * Virtual function called when handling each event.
+   *
+   * Returns: %TRUE if the plugin handled the event type (i.e., if the return
+   * value is %FALSE, there will be no subsequent call to the manager
+   * completed() callback, and the compositor must ensure that any appropriate
+   * post-effect cleanup is carried out.
    */
   gboolean (*xevent_filter) (MetaPlugin       *plugin,
                              XEvent           *event);
 
+  /**
+   * MetaPluginClass::keybinding_filter:
+   * @binding: a #MetaKeyBinding
+   *
+   * Virtual function called when handling each keybinding.
+   *
+   * Returns: %TRUE if the plugin handled the keybinding.
+   */
   gboolean (*keybinding_filter) (MetaPlugin     *plugin,
                                  MetaKeyBinding *binding);
 
+  /**
+   * MetaPluginClass::plugin_info:
+   * @plugin: a #MetaPlugin
+   *
+   * Virtual function that returns information about the #MetaPlugin.
+   *
+   * Returns: a #MetaPluginInfo.
+   */
   const MetaPluginInfo * (*plugin_info) (MetaPlugin *plugin);
 };
 
+/**
+ * MetaPluginInfo:
+ * @name: name of the plugin
+ * @version: version of the plugin
+ * @author: author of the plugin
+ * @license: license of the plugin
+ * @description: description of the plugin
+ */
 struct _MetaPluginInfo
 {
   const gchar *name;
@@ -127,6 +240,13 @@ gboolean      meta_plugin_debug_mode          (MetaPlugin *plugin);
 
 const MetaPluginInfo * meta_plugin_get_info (MetaPlugin *plugin);
 
+/**
+ * MetaPluginVersion:
+ * @version_major: major component of the version number of Meta with which the plugin was compiled
+ * @version_minor: minor component of the version number of Meta with which the plugin was compiled
+ * @version_micro: micro component of the version number of Meta with which the plugin was compiled
+ * @version_api: version of the plugin API
+ */
 struct _MetaPluginVersion
 {
   /*
diff --git a/src/meta/meta-shadow-factory.h b/src/meta/meta-shadow-factory.h
index 2782ac485..b95ec49f8 100644
--- a/src/meta/meta-shadow-factory.h
+++ b/src/meta/meta-shadow-factory.h
@@ -29,8 +29,6 @@
 
 /**
  * MetaShadowParams:
- * The #MetaShadowParams structure holds information about how to draw
- * a particular style of shadow.
  * @radius: the radius (gaussian standard deviation) of the shadow
  * @top_fade: if >= 0, the shadow doesn't extend above the top
  *  of the shape, and fades out over the given number of pixels
@@ -39,6 +37,9 @@
  * @y_offset: vertical offset of the shadow with respect to the
  *  shape being shadowed, in pixels
  * @opacity: opacity of the shadow, from 0 to 255
+ *
+ * The #MetaShadowParams structure holds information about how to draw
+ * a particular style of shadow.
  */
 
 typedef struct _MetaShadowParams MetaShadowParams;
@@ -61,6 +62,7 @@ struct _MetaShadowParams
 
 /**
  * MetaShadowFactory:
+ *
  * #MetaShadowFactory is used to create window shadows. It caches shadows internally
  * so that multiple shadows created for the same shape with the same radius will
  * share the same MetaShadow.
diff --git a/src/meta/meta-shaped-texture.h b/src/meta/meta-shaped-texture.h
index 9f37396d5..815b3ac98 100644
--- a/src/meta/meta-shaped-texture.h
+++ b/src/meta/meta-shaped-texture.h
@@ -44,6 +44,7 @@ typedef struct _MetaShapedTexturePrivate MetaShapedTexturePrivate;
 
 struct _MetaShapedTextureClass
 {
+  /*< private >*/
   ClutterActorClass parent_class;
 };
 
diff --git a/src/meta/meta-window-actor.h b/src/meta/meta-window-actor.h
index 68fb45f0b..40657d4f2 100644
--- a/src/meta/meta-window-actor.h
+++ b/src/meta/meta-window-actor.h
@@ -46,6 +46,7 @@ typedef struct _MetaWindowActorPrivate MetaWindowActorPrivate;
 
 struct _MetaWindowActorClass
 {
+  /*< private >*/
   ClutterActorClass parent_class;
 };
 
diff --git a/src/meta/prefs.h b/src/meta/prefs.h
index e2645090c..1723007e5 100644
--- a/src/meta/prefs.h
+++ b/src/meta/prefs.h
@@ -32,6 +32,44 @@
 #include <gdesktop-enums.h>
 #include <gio/gio.h>
 
+/**
+ * MetaPreference:
+ * @META_PREF_MOUSE_BUTTON_MODS: mouse button modifiers
+ * @META_PREF_FOCUS_MODE: focus mode
+ * @META_PREF_FOCUS_NEW_WINDOWS: focus new windows
+ * @META_PREF_ATTACH_MODAL_DIALOGS: attach modal dialogs
+ * @META_PREF_RAISE_ON_CLICK: raise on click
+ * @META_PREF_ACTION_DOUBLE_CLICK_TITLEBAR: action double click titlebar
+ * @META_PREF_ACTION_MIDDLE_CLICK_TITLEBAR: action middle click titlebar
+ * @META_PREF_ACTION_RIGHT_CLICK_TITLEBAR: action right click titlebar
+ * @META_PREF_AUTO_RAISE: auto-raise
+ * @META_PREF_AUTO_RAISE_DELAY: auto-raise delay
+ * @META_PREF_FOCUS_CHANGE_ON_POINTER_REST: focus change on pointer rest
+ * @META_PREF_THEME: theme
+ * @META_PREF_TITLEBAR_FONT: title-bar font
+ * @META_PREF_NUM_WORKSPACES: number of workspaces
+ * @META_PREF_DYNAMIC_WORKSPACES: dynamic workspaces
+ * @META_PREF_APPLICATION_BASED: application-based
+ * @META_PREF_KEYBINDINGS: keybindings
+ * @META_PREF_DISABLE_WORKAROUNDS: disable workarounds
+ * @META_PREF_BUTTON_LAYOUT: button layout
+ * @META_PREF_WORKSPACE_NAMES: workspace names
+ * @META_PREF_VISUAL_BELL: visual bell
+ * @META_PREF_AUDIBLE_BELL: audible bell
+ * @META_PREF_VISUAL_BELL_TYPE: visual bell type
+ * @META_PREF_GNOME_ACCESSIBILITY: GNOME accessibility
+ * @META_PREF_GNOME_ANIMATIONS: GNOME animations
+ * @META_PREF_CURSOR_THEME: cursor theme
+ * @META_PREF_CURSOR_SIZE: cursor size
+ * @META_PREF_RESIZE_WITH_RIGHT_BUTTON: resize with right button
+ * @META_PREF_EDGE_TILING: edge tiling
+ * @META_PREF_FORCE_FULLSCREEN: force fullscreen
+ * @META_PREF_WORKSPACES_ONLY_ON_PRIMARY: workspaces only on primary
+ * @META_PREF_NO_TAB_POPUP: no tab popup
+ * @META_PREF_DRAGGABLE_BORDER_WIDTH: draggable border width
+ * @META_PREF_AUTO_MAXIMIZE: auto-maximize
+ */
+
 /* Keep in sync with GSettings schemas! */
 typedef enum
 {
@@ -138,6 +176,93 @@ int      meta_prefs_get_draggable_border_width (void);
 gboolean meta_prefs_get_ignore_request_hide_titlebar (void);
 void     meta_prefs_set_ignore_request_hide_titlebar (gboolean whether);
 
+/**
+ * MetaKeyBindingAction:
+ * @META_KEYBINDING_ACTION_NONE: FILLME 
+ * @META_KEYBINDING_ACTION_WORKSPACE_1: FILLME 
+ * @META_KEYBINDING_ACTION_WORKSPACE_2: FILLME 
+ * @META_KEYBINDING_ACTION_WORKSPACE_3: FILLME 
+ * @META_KEYBINDING_ACTION_WORKSPACE_4: FILLME 
+ * @META_KEYBINDING_ACTION_WORKSPACE_5: FILLME 
+ * @META_KEYBINDING_ACTION_WORKSPACE_6: FILLME 
+ * @META_KEYBINDING_ACTION_WORKSPACE_7: FILLME 
+ * @META_KEYBINDING_ACTION_WORKSPACE_8: FILLME 
+ * @META_KEYBINDING_ACTION_WORKSPACE_9: FILLME 
+ * @META_KEYBINDING_ACTION_WORKSPACE_10: FILLME 
+ * @META_KEYBINDING_ACTION_WORKSPACE_11: FILLME 
+ * @META_KEYBINDING_ACTION_WORKSPACE_12: FILLME 
+ * @META_KEYBINDING_ACTION_WORKSPACE_LEFT: FILLME 
+ * @META_KEYBINDING_ACTION_WORKSPACE_RIGHT: FILLME 
+ * @META_KEYBINDING_ACTION_WORKSPACE_UP: FILLME 
+ * @META_KEYBINDING_ACTION_WORKSPACE_DOWN: FILLME 
+ * @META_KEYBINDING_ACTION_SWITCH_APPLICATIONS: FILLME 
+ * @META_KEYBINDING_ACTION_SWITCH_APPLICATIONS_BACKWARD: FILLME 
+ * @META_KEYBINDING_ACTION_SWITCH_GROUP: FILLME 
+ * @META_KEYBINDING_ACTION_SWITCH_GROUP_BACKWARD: FILLME 
+ * @META_KEYBINDING_ACTION_SWITCH_WINDOWS: FILLME 
+ * @META_KEYBINDING_ACTION_SWITCH_WINDOWS_BACKWARD: FILLME 
+ * @META_KEYBINDING_ACTION_SWITCH_PANELS: FILLME 
+ * @META_KEYBINDING_ACTION_SWITCH_PANELS_BACKWARD: FILLME 
+ * @META_KEYBINDING_ACTION_CYCLE_GROUP: FILLME 
+ * @META_KEYBINDING_ACTION_CYCLE_GROUP_BACKWARD: FILLME 
+ * @META_KEYBINDING_ACTION_CYCLE_WINDOWS: FILLME 
+ * @META_KEYBINDING_ACTION_CYCLE_WINDOWS_BACKWARD: FILLME 
+ * @META_KEYBINDING_ACTION_CYCLE_PANELS: FILLME 
+ * @META_KEYBINDING_ACTION_CYCLE_PANELS_BACKWARD: FILLME 
+ * @META_KEYBINDING_ACTION_TAB_POPUP_SELECT: FILLME 
+ * @META_KEYBINDING_ACTION_TAB_POPUP_CANCEL: FILLME 
+ * @META_KEYBINDING_ACTION_SHOW_DESKTOP: FILLME 
+ * @META_KEYBINDING_ACTION_PANEL_MAIN_MENU: FILLME 
+ * @META_KEYBINDING_ACTION_PANEL_RUN_DIALOG: FILLME 
+ * @META_KEYBINDING_ACTION_TOGGLE_RECORDING: FILLME 
+ * @META_KEYBINDING_ACTION_SET_SPEW_MARK: FILLME 
+ * @META_KEYBINDING_ACTION_ACTIVATE_WINDOW_MENU: FILLME 
+ * @META_KEYBINDING_ACTION_TOGGLE_FULLSCREEN: FILLME 
+ * @META_KEYBINDING_ACTION_TOGGLE_MAXIMIZED: FILLME 
+ * @META_KEYBINDING_ACTION_TOGGLE_TILED_LEFT: FILLME 
+ * @META_KEYBINDING_ACTION_TOGGLE_TILED_RIGHT: FILLME 
+ * @META_KEYBINDING_ACTION_TOGGLE_ABOVE: FILLME 
+ * @META_KEYBINDING_ACTION_MAXIMIZE: FILLME 
+ * @META_KEYBINDING_ACTION_UNMAXIMIZE: FILLME 
+ * @META_KEYBINDING_ACTION_TOGGLE_SHADED: FILLME 
+ * @META_KEYBINDING_ACTION_MINIMIZE: FILLME 
+ * @META_KEYBINDING_ACTION_CLOSE: FILLME 
+ * @META_KEYBINDING_ACTION_BEGIN_MOVE: FILLME 
+ * @META_KEYBINDING_ACTION_BEGIN_RESIZE: FILLME 
+ * @META_KEYBINDING_ACTION_TOGGLE_ON_ALL_WORKSPACES: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_WORKSPACE_1: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_WORKSPACE_2: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_WORKSPACE_3: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_WORKSPACE_4: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_WORKSPACE_5: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_WORKSPACE_6: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_WORKSPACE_7: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_WORKSPACE_8: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_WORKSPACE_9: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_WORKSPACE_10: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_WORKSPACE_11: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_WORKSPACE_12: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_WORKSPACE_LEFT: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_WORKSPACE_RIGHT: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_WORKSPACE_UP: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_WORKSPACE_DOWN: FILLME 
+ * @META_KEYBINDING_ACTION_RAISE_OR_LOWER: FILLME 
+ * @META_KEYBINDING_ACTION_RAISE: FILLME 
+ * @META_KEYBINDING_ACTION_LOWER: FILLME 
+ * @META_KEYBINDING_ACTION_MAXIMIZE_VERTICALLY: FILLME 
+ * @META_KEYBINDING_ACTION_MAXIMIZE_HORIZONTALLY: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_CORNER_NW: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_CORNER_NE: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_CORNER_SW: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_CORNER_SE: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_SIDE_N: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_SIDE_S: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_SIDE_E: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_SIDE_W: FILLME 
+ * @META_KEYBINDING_ACTION_MOVE_TO_CENTER: FILLME 
+ * @META_KEYBINDING_ACTION_OVERLAY_KEY: FILLME 
+ * @META_KEYBINDING_ACTION_LAST: FILLME 
+ */
 /* XXX FIXME This should be x-macroed, but isn't yet because it would be
  * difficult (or perhaps impossible) to add the suffixes using the current
  * system.  It needs some more thought, perhaps after the current system
@@ -232,6 +357,14 @@ typedef enum _MetaKeyBindingAction
   META_KEYBINDING_ACTION_LAST
 } MetaKeyBindingAction;
 
+/**
+ * MetaKeyBindingFlags:
+ * @META_KEY_BINDING_NONE: none
+ * @META_KEY_BINDING_PER_WINDOW: per-window
+ * @META_KEY_BINDING_BUILTIN: built-in
+ * @META_KEY_BINDING_REVERSES: reverses
+ * @META_KEY_BINDING_IS_REVERSED: is reversed
+ */
 typedef enum
 {
   META_KEY_BINDING_NONE,
@@ -241,6 +374,12 @@ typedef enum
   META_KEY_BINDING_IS_REVERSED = 1 << 3
 } MetaKeyBindingFlags;
 
+/**
+ * MetaKeyCombo:
+ * @keysym: keysym
+ * @keycode: keycode
+ * @modifiers: modifiers
+ */
 typedef struct
 {
   unsigned int keysym;
@@ -250,7 +389,12 @@ typedef struct
 
 /**
  * MetaKeyHandlerFunc:
- * @event: (type gpointer):
+ * @display: a #MetaDisplay
+ * @screen: a #MetaScreen
+ * @window: a #MetaWindow
+ * @event: (type gpointer): a #XIDeviceEvent
+ * @binding: a #MetaKeyBinding
+ * @user_data: data passed to the function
  *
  */
 typedef void (* MetaKeyHandlerFunc) (MetaDisplay    *display,
diff --git a/src/meta/preview-widget.h b/src/meta/preview-widget.h
index dfba41aa1..2a7919485 100644
--- a/src/meta/preview-widget.h
+++ b/src/meta/preview-widget.h
@@ -62,6 +62,7 @@ struct _MetaPreview
 
 struct _MetaPreviewClass
 {
+  /*< private >*/
   GtkBinClass parent_class;
 };
 
diff --git a/src/meta/screen.h b/src/meta/screen.h
index ad647624a..de36dba01 100644
--- a/src/meta/screen.h
+++ b/src/meta/screen.h
@@ -88,6 +88,13 @@ int meta_screen_get_monitor_index_for_rect (MetaScreen    *screen,
 void meta_screen_focus_default_window (MetaScreen *screen,
                                        guint32     timestamp);
 
+/**
+ * MetaScreenCorner:
+ * @META_SCREEN_TOPLEFT: top-left corner
+ * @META_SCREEN_TOPRIGHT: top-right corner
+ * @META_SCREEN_BOTTOMLEFT: bottom-left corner
+ * @META_SCREEN_BOTTOMRIGHT: bottom-right corner
+ */
 typedef enum
 {
   META_SCREEN_TOPLEFT,
diff --git a/src/meta/util.h b/src/meta/util.h
index b34d93569..9e02484b8 100644
--- a/src/meta/util.h
+++ b/src/meta/util.h
@@ -50,6 +50,32 @@ void meta_warning    (const char *format,
 void meta_fatal      (const char *format,
                       ...) G_GNUC_PRINTF (1, 2);
 
+/**
+ * MetaDebugTopic:
+ * @META_DEBUG_VERBOSE: verbose logging
+ * @META_DEBUG_FOCUS: focus
+ * @META_DEBUG_WORKAREA: workarea
+ * @META_DEBUG_STACK: stack
+ * @META_DEBUG_THEMES: themes
+ * @META_DEBUG_SM: session management
+ * @META_DEBUG_EVENTS: events
+ * @META_DEBUG_WINDOW_STATE: window state
+ * @META_DEBUG_WINDOW_OPS: window operations
+ * @META_DEBUG_GEOMETRY: geometry
+ * @META_DEBUG_PLACEMENT: window placement
+ * @META_DEBUG_PING: ping
+ * @META_DEBUG_XINERAMA: Xinerama
+ * @META_DEBUG_KEYBINDINGS: keybindings
+ * @META_DEBUG_SYNC: sync
+ * @META_DEBUG_ERRORS: errors
+ * @META_DEBUG_STARTUP: startup
+ * @META_DEBUG_PREFS: preferences
+ * @META_DEBUG_GROUPS: groups
+ * @META_DEBUG_RESIZING: resizing
+ * @META_DEBUG_SHAPES: shapes
+ * @META_DEBUG_COMPOSITOR: compositor
+ * @META_DEBUG_EDGE_RESISTANCE: edge resistance
+ */
 typedef enum
 {
   META_DEBUG_VERBOSE         = -1,
diff --git a/src/meta/window.h b/src/meta/window.h
index 0c5fbb041..07ca88b0c 100644
--- a/src/meta/window.h
+++ b/src/meta/window.h
@@ -29,6 +29,25 @@
 #include <meta/boxes.h>
 #include <meta/types.h>
 
+/**
+ * MetaWindowType:
+ * @META_WINDOW_NORMAL: Normal
+ * @META_WINDOW_DESKTOP: Desktop
+ * @META_WINDOW_DOCK: Dock
+ * @META_WINDOW_DIALOG: Dialog
+ * @META_WINDOW_MODAL_DIALOG: Modal dialog
+ * @META_WINDOW_TOOLBAR: Toolbar
+ * @META_WINDOW_MENU: Menu
+ * @META_WINDOW_UTILITY: Utility
+ * @META_WINDOW_SPLASHSCREEN: Splashcreen
+ * @META_WINDOW_DROPDOWN_MENU: Dropdown menu
+ * @META_WINDOW_POPUP_MENU: Popup menu
+ * @META_WINDOW_TOOLTIP: Tooltip
+ * @META_WINDOW_NOTIFICATION: Notification
+ * @META_WINDOW_COMBO: Combobox
+ * @META_WINDOW_DND: Drag and drop
+ * @META_WINDOW_OVERRIDE_OTHER: Other override-redirect window type
+ */
 typedef enum
 {
   META_WINDOW_NORMAL,
@@ -51,6 +70,11 @@ typedef enum
   META_WINDOW_OVERRIDE_OTHER
 } MetaWindowType;
 
+/**
+ * MetaMaximizeFlags:
+ * @META_MAXIMIZE_HORIZONTAL: Horizontal
+ * @META_MAXIMIZE_VERTICAL: Vertical
+ */
 typedef enum
 {
   META_MAXIMIZE_HORIZONTAL = 1 << 0,
diff --git a/src/meta/workspace.h b/src/meta/workspace.h
index 66efe0fff..7e0ce3cd7 100644
--- a/src/meta/workspace.h
+++ b/src/meta/workspace.h
@@ -24,7 +24,7 @@
 #define META_WORKSPACE_H
 
 /**
- * SECTION:Workspaces
+ * SECTION:workspace
  * @short_description:Workspaces
  *
  * A workspace is a set of windows which all live on the same
diff --git a/src/ui/gradient.c b/src/ui/gradient.c
index 21ae422e4..d6e872fa4 100644
--- a/src/ui/gradient.c
+++ b/src/ui/gradient.c
@@ -172,6 +172,12 @@ meta_gradient_create_multi (int              width,
 
 /**
  * meta_gradient_create_interwoven: (skip)
+ * @width: Width in pixels
+ * @height: Height in pixels
+ * @colors1: Array of colors
+ * @thickness1: Thickness
+ * @colors2: Array of colors
+ * @thickness2: Thickness
  *
  * Interwoven essentially means we have two vertical gradients,
  * cut into horizontal strips of the given thickness, and then the strips
diff --git a/src/ui/theme-parser.c b/src/ui/theme-parser.c
index 5711a3c43..c5b4308a3 100644
--- a/src/ui/theme-parser.c
+++ b/src/ui/theme-parser.c
@@ -4267,6 +4267,8 @@ keep_trying (GError **error)
 
 /**
  * meta_theme_load: (skip)
+ * @theme_name: 
+ * @err: 
  *
  */
 MetaTheme*
diff --git a/src/ui/theme.c b/src/ui/theme.c
index 67697ec05..bf57016fb 100644
--- a/src/ui/theme.c
+++ b/src/ui/theme.c
@@ -6212,6 +6212,7 @@ meta_frame_type_from_string (const char *str)
 
 /**
  * meta_frame_type_to_string:
+ * @type: a #MetaFrameType
  *
  * Converts a frame type enum value to the name string that would
  * appear in the theme definition file.