diff --git a/clutter/clutter/cally/cally.c b/clutter/clutter/cally/cally.c
index 247fa1662..4b6194988 100644
--- a/clutter/clutter/cally/cally.c
+++ b/clutter/clutter/cally/cally.c
@@ -17,16 +17,6 @@
  * You should have received a copy of the GNU Lesser General Public
  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  */
-
-/**
- * SECTION:cally
- * @Title: Cally
- * @short_description: Cally initialization methods.
- *
- * Cally initialization methods.
- *
- */
-
 #include "config.h"
 
 #include "cally/cally.h"
diff --git a/clutter/clutter/clutter-base-types.c b/clutter/clutter/clutter-base-types.c
index 61b274b46..db581ea12 100644
--- a/clutter/clutter/clutter-base-types.c
+++ b/clutter/clutter/clutter-base-types.c
@@ -20,16 +20,6 @@
  * You should have received a copy of the GNU Lesser General Public
  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  */
-
-/**
- * SECTION:clutter-geometric-types
- * @Title: Base geometric types
- * @Short_Description: Common geometric data types used by Clutter
- *
- * Clutter defines a set of geometric data structures that are commonly used
- * across the whole API.
- */
-
 #include "config.h"
 
 #include "clutter/clutter-types.h"
diff --git a/clutter/clutter/clutter-blur.c b/clutter/clutter/clutter-blur.c
index 6b2839c76..6b5d3adeb 100644
--- a/clutter/clutter/clutter-blur.c
+++ b/clutter/clutter/clutter-blur.c
@@ -20,8 +20,9 @@
 #include "clutter/clutter-backend.h"
 
 /**
- * SECTION:clutter-blur
- * @short_description: Blur textures
+ * ClutterBlur:
+ *
+ * Blur textures
  *
  * #ClutterBlur is a moderately fast gaussian blur implementation.
  *
diff --git a/clutter/clutter/clutter-feature.c b/clutter/clutter/clutter-feature.c
index 8eff2f512..2294cc2e9 100644
--- a/clutter/clutter/clutter-feature.c
+++ b/clutter/clutter/clutter-feature.c
@@ -24,8 +24,7 @@
  */
 
 /**
- * SECTION:clutter-feature
- * @short_description: Run-time detection of Clutter features
+ * Run-time detection of Clutter features
  *
  * Parts of Clutter depend on the underlying platform, including the
  * capabilities of the backend used and the OpenGL features exposed through the
diff --git a/clutter/clutter/clutter-main.c b/clutter/clutter/clutter-main.c
index b34790f9f..de3362827 100644
--- a/clutter/clutter/clutter-main.c
+++ b/clutter/clutter/clutter-main.c
@@ -20,33 +20,6 @@
  * You should have received a copy of the GNU Lesser General Public
  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  */
-
-/**
- * SECTION:clutter-main
- * @short_description: Various 'global' Clutter functions.
- *
- * Functions to retrieve various global Clutter resources and other utility
- * functions for mainloops, events and threads
- *
- * ## The Clutter Threading Model
- *
- * Clutter is *thread-aware*: all operations performed by Clutter are assumed
- * to be under the Big Clutter Lock, which is created when the threading is
- * initialized through clutter_init(), and entered when calling user-related
- * code during event handling and actor drawing.
- *
- * The only safe and portable way to use the Clutter API in a multi-threaded
- * environment is to only access the Clutter API from a thread that did called
- * clutter_init() and clutter_main().
- *
- * The common pattern for using threads with Clutter is to use worker threads
- * to perform blocking operations and then install idle or timeout sources with
- * the result when the thread finishes, and update the UI from those callbacks.
- *
- * For a working example of how to use a worker thread to update the UI, see
- * [threads.c](https://git.gnome.org/browse/clutter/tree/examples/threads.c?h=clutter-1.18)
- */
-
 #include "config.h"
 
 #include <stdlib.h>
diff --git a/clutter/clutter/clutter-util.c b/clutter/clutter/clutter-util.c
index 17d20990c..973a9f29d 100644
--- a/clutter/clutter/clutter-util.c
+++ b/clutter/clutter/clutter-util.c
@@ -22,14 +22,6 @@
  *
  *
  */
-
-/**
- * SECTION:clutter-util
- * @short_description: Utility functions
- *
- * Various miscellaneous utilility functions.
- */
-
 #include "config.h"
 
 #include <fribidi.h>
diff --git a/cogl/cogl/cogl-depth-state.h b/cogl/cogl/cogl-depth-state.h
index 0d8fe18fb..e32f97e86 100644
--- a/cogl/cogl/cogl-depth-state.h
+++ b/cogl/cogl/cogl-depth-state.h
@@ -38,15 +38,10 @@
 
 G_BEGIN_DECLS
 
-/**
- * SECTION:cogl-depth-state
- * @short_description: Functions for describing the depth testing
- *                     state of your GPU.
- */
-
 /**
  * CoglDepthState:
- *
+ * 
+ * Functions for describing the depth testing state of your GPU.
  */
 typedef struct {
   /*< private >*/
diff --git a/cogl/cogl/cogl-fence.h b/cogl/cogl/cogl-fence.h
index d2e6f4e7c..3e70c3bf8 100644
--- a/cogl/cogl/cogl-fence.h
+++ b/cogl/cogl/cogl-fence.h
@@ -38,21 +38,14 @@
 #include "cogl/cogl-framebuffer.h"
 
 /**
- * SECTION:cogl-fence
- * @short_description: Functions for notification of command completion
+ * CoglFence:
+ *
+ * Functions for notification of command completion
  *
  * Cogl allows notification of GPU command completion; users may mark
  * points in the GPU command stream and receive notification when the GPU
  * has executed to that point.
  */
-
-/**
- * CoglFence:
- *
- * An opaque object representing a fence. This type is currently
- * unused but in the future may be used to pass extra information
- * about the fence completion.
- */
 typedef struct _CoglFence CoglFence;
 
 /**
diff --git a/cogl/cogl/cogl-framebuffer.h b/cogl/cogl/cogl-framebuffer.h
index 3d9aee093..92b495afa 100644
--- a/cogl/cogl/cogl-framebuffer.h
+++ b/cogl/cogl/cogl-framebuffer.h
@@ -47,8 +47,9 @@
 G_BEGIN_DECLS
 
 /**
- * SECTION:cogl-framebuffer
- * @short_description: A common interface for manipulating framebuffers
+ * CoglFrameBuffer:
+ *
+ * A common interface for manipulating framebuffers
  *
  * Framebuffers are a collection of buffers that can be rendered too.
  * A framebuffer may be comprised of one or more color buffers, an
diff --git a/cogl/cogl/cogl-matrix-stack.h b/cogl/cogl/cogl-matrix-stack.h
index a679da227..343c53394 100644
--- a/cogl/cogl/cogl-matrix-stack.h
+++ b/cogl/cogl/cogl-matrix-stack.h
@@ -42,61 +42,11 @@
 
 #include <graphene.h>
 
-/**
- * SECTION:cogl-matrix-stack
- * @short_description: Functions for efficiently tracking many
- *                     related transformations
- *
- * Matrices can be used (for example) to describe the model-view
- * transforms of objects, texture transforms, and projective
- * transforms.
- *
- * The #graphene_matrix_t api provides a good way to manipulate individual
- * matrices representing a single transformation but if you need to
- * track many-many such transformations for many objects that are
- * organized in a scenegraph for example then using a separate
- * #graphene_matrix_t for each object may not be the most efficient way.
- *
- * A #CoglMatrixStack enables applications to track lots of
- * transformations that are related to each other in some kind of
- * hierarchy.  In a scenegraph for example if you want to know how to
- * transform a particular node then you usually have to walk up
- * through the ancestors and accumulate their transforms before
- * finally applying the transform of the node itself. In this model
- * things are grouped together spatially according to their ancestry
- * and all siblings with the same parent share the same initial
- * transformation. The #CoglMatrixStack API is suited to tracking lots
- * of transformations that fit this kind of model.
- *
- * Compared to using the #graphene_matrix_t api directly to track many
- * related transforms, these can be some advantages to using a
- * #CoglMatrixStack:
- *
- * - Faster equality comparisons of transformations
- * - Efficient comparisons of the differences between arbitrary
- *   transformations
- * - Avoid redundant arithmetic related to common transforms
- * - Can be more space efficient (not always though)
- *
- * For reference (to give an idea of when a #CoglMatrixStack can
- * provide a space saving) a #graphene_matrix_t can be expected to take 72
- * bytes whereas a single #CoglMatrixEntry in a #CoglMatrixStack is
- * currently around 32 bytes on a 32bit CPU or 36 bytes on a 64bit
- * CPU. An entry is needed for each individual operation applied to
- * the stack (such as rotate, scale, translate) so if most of your
- * leaf node transformations only need one or two simple operations
- * relative to their parent then a matrix stack will likely take less
- * space than having a #graphene_matrix_t for each node.
- *
- * Even without any space saving though the ability to perform fast
- * comparisons and avoid redundant arithmetic (especially sine and
- * cosine calculations for rotations) can make using a matrix stack
- * worthwhile.
- */
-
 /**
  * CoglMatrixStack:
  *
+ * Efficiently tracking many related transformations.
+ *
  * Tracks your current position within a hierarchy and lets you build
  * up a graph of transformations as you traverse through a hierarchy
  * such as a scenegraph.
diff --git a/cogl/cogl/cogl-meta-texture.h b/cogl/cogl/cogl-meta-texture.h
index 0d4421379..8257df7e2 100644
--- a/cogl/cogl/cogl-meta-texture.h
+++ b/cogl/cogl/cogl-meta-texture.h
@@ -39,9 +39,8 @@
 G_BEGIN_DECLS
 
 /**
- * SECTION:cogl-meta-texture
- * @short_description: Interface for high-level textures built from
- *                     low-level textures like #CoglTexture2D.
+ * Interface for high-level textures built from 
+ * low-level textures like #CoglTexture2D.
  *
  * Cogl helps to make it easy to deal with high level textures such
  * as `CoglAtlasTexture`s, `CoglSubTexture`s,
diff --git a/cogl/cogl/cogl-offscreen.h b/cogl/cogl/cogl-offscreen.h
index 277acb615..b97807ab3 100644
--- a/cogl/cogl/cogl-offscreen.h
+++ b/cogl/cogl/cogl-offscreen.h
@@ -42,11 +42,9 @@
 G_BEGIN_DECLS
 
 /**
- * SECTION:cogl-offscreen
- * @short_description: Functions for creating and manipulating offscreen
- *                     framebuffers.
+ * CoglOffscreen:
  *
- * Cogl allows creating and operating on offscreen framebuffers.
+ * Functions for creating and manipulating offscreen framebuffers.
  */
 
 /* Offscreen api */
diff --git a/cogl/cogl/cogl-pipeline-private.h b/cogl/cogl/cogl-pipeline-private.h
index ad256909d..fd6d4fdbe 100644
--- a/cogl/cogl/cogl-pipeline-private.h
+++ b/cogl/cogl/cogl-pipeline-private.h
@@ -490,17 +490,6 @@ void
 _cogl_pipeline_prune_empty_layer_difference (CoglPipeline *layers_authority,
                                              CoglPipelineLayer *layer);
 
-/*
- * SECTION:cogl-pipeline-internals
- * @short_description: Functions for creating custom primitives that make use
- *    of Cogl pipelines for filling.
- *
- * Normally you shouldn't need to use this API directly, but if you need to
- * developing a custom/specialised primitive - probably using raw OpenGL - then
- * this API aims to expose enough of the pipeline internals to support being
- * able to fill your geometry according to a given Cogl pipeline.
- */
-
 gboolean
 _cogl_pipeline_get_real_blend_enabled (CoglPipeline *pipeline);
 
diff --git a/cogl/cogl/cogl-pixel-format.h b/cogl/cogl/cogl-pixel-format.h
index 7995ae017..3c90cd718 100644
--- a/cogl/cogl/cogl-pixel-format.h
+++ b/cogl/cogl/cogl-pixel-format.h
@@ -45,21 +45,6 @@
 
 G_BEGIN_DECLS
 
-/**
- * SECTION:cogl-pixel-format
- * @short_description: Pixel formats supported by Cogl
- *
- * The pixel format of an image descrbes how the bits of each pixel are
- * represented in memory. For example: an image can be laid out as one long
- * sequence of pixels, where each pixel is a sequence of 8 bits of Red, Green
- * and Blue. The amount of bits that are used can be different for each pixel
- * format, as well as the components (for example an Alpha layer to include
- * transparency, or non_RGBA).
- *
- * Other examples of factors that can influence the layout in memory are the
- * system's endianness.
- */
-
 #define COGL_A_BIT              (1 << 4)
 #define COGL_BGR_BIT            (1 << 5)
 #define COGL_AFIRST_BIT         (1 << 6)
diff --git a/cogl/cogl/cogl-poll.h b/cogl/cogl/cogl-poll.h
index 652b2146c..3062ec138 100644
--- a/cogl/cogl/cogl-poll.h
+++ b/cogl/cogl/cogl-poll.h
@@ -51,9 +51,9 @@
 G_BEGIN_DECLS
 
 /**
- * SECTION:cogl-poll
- * @short_description: Functions for integrating Cogl with an
- *   application's main loop
+ * CoglPoll:
+ *
+ * Functions for integrating Cogl with an application's main loop
  *
  * Cogl needs to integrate with the application's main loop so that it
  * can internally handle some events from the driver. All Cogl
diff --git a/cogl/cogl/cogl-types.h b/cogl/cogl/cogl-types.h
index 042eae901..e46c94880 100644
--- a/cogl/cogl/cogl-types.h
+++ b/cogl/cogl/cogl-types.h
@@ -46,13 +46,6 @@
 
 G_BEGIN_DECLS
 
-/**
- * SECTION:cogl-types
- * @short_description: Types used throughout the library
- *
- * General types used by various Cogl functions.
-*/
-
 /* Some structures are meant to be opaque but they have public
    definitions because we want the size to be public so they can be
    allocated on the stack. This macro is used to ensure that users
diff --git a/cogl/cogl/cogl.h b/cogl/cogl/cogl.h
index 2183b2e3e..50f042c79 100644
--- a/cogl/cogl/cogl.h
+++ b/cogl/cogl/cogl.h
@@ -99,13 +99,6 @@
  * code has been migrated down into Cogl! */
 #include "cogl/deprecated/cogl-clutter.h"
 
-/**
- * SECTION:cogl
- * @short_description: General purpose API
- *
- * General utility functions for COGL.
- */
-
 /* The gobject introspection scanner seems to parse public headers in
  * isolation which means we need to be extra careful about how we
  * define and undefine __COGL_H_INSIDE__ used to detect when internal
diff --git a/src/compositor/meta-multi-texture-format.c b/src/compositor/meta-multi-texture-format.c
index b5e3aa2e9..857531f58 100644
--- a/src/compositor/meta-multi-texture-format.c
+++ b/src/compositor/meta-multi-texture-format.c
@@ -16,20 +16,6 @@
  * You should have received a copy of the GNU General Public License
  * along with this program; if not, see <http://www.gnu.org/licenses/>.
  */
-
-/**
- * SECTION:meta-multi-texture-format
- * @title: MetaMultiTextureFormat
- * @short_description: A representation for complex pixel formats
- *
- * Some pixel formats that are used in the wild are a bit more complex than
- * just ARGB and all its variants. For example: a component might be put in a
- * different plane (i.e. at a different place in memory). Another example are
- * formats that use Y, U, and V components rather than RGB; if we composite them
- * onto an RGBA framebuffer, we have to make sure for example that these get
- * converted to the right color format first (using e.g. a shader).
- */
-
 #include "config.h"
 
 #include "compositor/meta-multi-texture-format-private.h"
diff --git a/src/compositor/meta-multi-texture.c b/src/compositor/meta-multi-texture.c
index 793d48d7a..d336cb5a6 100644
--- a/src/compositor/meta-multi-texture.c
+++ b/src/compositor/meta-multi-texture.c
@@ -18,9 +18,9 @@
  */
 
 /**
- * SECTION:meta-multi-texture
- * @title: MetaMultiTexture
- * @short_description: A texture that can have multiple planes.
+ * MetaMultiTexture:
+ *
+ * A texture that can have multiple planes.
  *
  * #MetaMultiTexture allows one to deal with non-trivial formats that
  * have multiple planes, requires subsampling and/or aren't in RGB. A common
diff --git a/src/core/display.c b/src/core/display.c
index d6cb733dd..39ff47ce8 100644
--- a/src/core/display.c
+++ b/src/core/display.c
@@ -97,8 +97,6 @@
 #endif
 
 /*
- * 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"
  * message within a reasonable time. Here we have a system which lets us
diff --git a/src/meta/meta-multi-texture-format.h b/src/meta/meta-multi-texture-format.h
index 1bb752259..9ed99624d 100644
--- a/src/meta/meta-multi-texture-format.h
+++ b/src/meta/meta-multi-texture-format.h
@@ -30,6 +30,15 @@ G_BEGIN_DECLS
  * @META_MULTI_TEXTURE_FORMAT_YUYV: YUYV, 32 bits, 16 bpc (Y), 8 bpc (U & V)
  * @META_MULTI_TEXTURE_FORMAT_NV12: 2 planes: 1 Y-plane, 1 UV-plane (2x2 subsampled)
  * @META_MULTI_TEXTURE_FORMAT_YUV420: 3 planes: 1 Y-plane, 1 U-plane (2x2 subsampled), 1 V-plane (2x2 subsampled)
+ * 
+ * A representation for complex pixel formats
+ *
+ * Some pixel formats that are used in the wild are a bit more complex than
+ * just ARGB and all its variants. For example: a component might be put in a
+ * different plane (i.e. at a different place in memory). Another example are
+ * formats that use Y, U, and V components rather than RGB; if we composite them
+ * onto an RGBA framebuffer, we have to make sure for example that these get
+ * converted to the right color format first (using e.g. a shader).
  */
 typedef enum _MetaMultiTextureFormat
 {
diff --git a/src/wayland/meta-wayland-client.c b/src/wayland/meta-wayland-client.c
index 351f13e75..ecb3b0ebe 100644
--- a/src/wayland/meta-wayland-client.c
+++ b/src/wayland/meta-wayland-client.c
@@ -19,9 +19,8 @@
  */
 
 /**
- * SECTION: meta-wayland-client
- * @title MetaWaylandClient
- * @include: gio/gsubprocess.h
+ * MetaWaylandClient:
+ * 
  * A class that allows to launch a trusted client and detect if an specific
  * Wayland window belongs to it.
  */