Add a meaningful name and description to all sections/files in the API docs

https://bugzilla.gnome.org/show_bug.cgi?id=695641

doc/reference/meta-sections.txt

@@ -104,10 +104,6 @@ meta_compositor_queue_frame_drawn
 meta_compositor_sync_stack
 meta_compositor_sync_screen_size
 meta_compositor_flash_screen
-</SECTION>
-
-<SECTION>
-<FILE>compositor-mutter</FILE>
 meta_get_stage_for_screen
 meta_get_overlay_group_for_screen
 meta_get_overlay_window
@@ -233,6 +229,7 @@ meta_quit
 <FILE>meta-background</FILE>
 <TITLE>MetaBackground</TITLE>
 MetaBackgroundEffects
+MetaBackground
 MetaBackgroundClass
 meta_background_new
 meta_background_copy

src/compositor/meta-background-actor.c

@@ -1,7 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 /*
- * meta-background-actor.c: Actor for painting the root window background
- *
  * Copyright 2009 Sander Dijkhuis
  * Copyright 2010 Red Hat, Inc.
  *
@@ -23,6 +21,13 @@
  * Portions adapted from gnome-shell/src/shell-global.c
  */
 
+/**
+ * SECTION:meta-background-actor
+ * @title: MetaBackgroundActor
+ * @short_description: Actor for painting the root window background
+ *
+ */
+
 #include <config.h>
 
 #include <cogl/cogl-texture-pixmap-x11.h>

src/compositor/meta-background-group.c

@@ -1,5 +1,19 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
+/**
+ * SECTION:meta-background-group
+ * @title: MetaBackgroundGroup
+ * @short_description: Container for background actors
+ *
+ * This class is a subclass of ClutterActor with special handling for
+ * MetaBackgroundActor/MetaBackgroundGroup when painting children.
+ * It makes sure to only draw the parts of the backgrounds not
+ * occluded by opaque windows.
+ *
+ * See #MetaWindowGroup for more information behind the motivation,
+ * and details on implementation.
+ */
+
 #include <config.h>
 
 #include "compositor-private.h"

src/compositor/meta-background.c

@@ -1,7 +1,6 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
+
 /*
- * meta-background.c: CoglTexture for painting the system background
- *
  * Copyright 2013 Red Hat, Inc.
  *
  * This program is free software; you can redistribute it and/or
@@ -20,6 +19,13 @@
  * 02111-1307, USA.
  */
 
+/**
+ * SECTION:meta-background
+ * @title: MetaBackground
+ * @short_description: ClutterContent for painting the system background
+ *
+ */
+
 #include <config.h>
 
 #include <cogl/cogl-texture-pixmap-x11.h>

src/compositor/meta-plugin.c

@@ -21,6 +21,13 @@
  * 02111-1307, USA.
  */
 
+/**
+ * SECTION:meta-plugin
+ * @title: MetaPlugin
+ * @short_description: Entry point for plugins
+ *
+ */
+
 #include <meta/meta-plugin.h>
 #include "meta-plugin-manager.h"
 #include <meta/screen.h>

src/compositor/meta-shadow-factory.c

@@ -1,9 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 /*
- * MetaShadowFactory:
- *
- * Create and cache shadow textures for abritrary window shapes
- *
  * Copyright 2010 Red Hat, Inc.
  *
  * This program is free software; you can redistribute it and/or
@@ -21,6 +17,13 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
  * 02111-1307, USA.
  */
+
+/**
+ * SECTION:meta-shadow-factory
+ * @title: MetaShadowFactory
+ * @short_description: Create and cache shadow textures for abritrary window shapes
+ */
+
 #include <config.h>
 #include <math.h>
 #include <string.h>

src/compositor/meta-shaped-texture.c

@@ -1,8 +1,4 @@
 /*
- * shaped texture
- *
- * An actor to draw a masked texture.
- *
  * Authored By Neil Roberts  <neil@linux.intel.com>
  * and Jasper St. Pierre <jstpierre@mecheye.net>
  *
@@ -25,6 +21,12 @@
  * 02111-1307, USA.
  */
 
+/**
+ * SECTION:meta-shaped-texture
+ * @title: MetaShapedTexture
+ * @short_description: An actor to draw a masked texture.
+ */
+
 #include <config.h>
 
 #include <meta/meta-shaped-texture.h>

src/compositor/meta-window-actor.c

@@ -1,5 +1,11 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
+/**
+ * SECTION:meta-window-actor
+ * @title: MetaWindowActor
+ * @short_description: An actor representing a top-level window in the scene graph
+ */
+
 #include <config.h>
 
 #include <math.h>

src/core/barrier.c

@@ -1,5 +1,11 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; c-basic-offset: 2; -*- */
 
+/**
+ * SECTION:barrier
+ * @Title: MetaBarrier
+ * @Short_Description: Pointer barriers
+ */
+
 #include "config.h"
 
 #include <glib-object.h>

src/core/boxes.c

@@ -1,6 +1,10 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* Simple box operations */
+/**
+ * SECTION:boxes
+ * @Title: MetaRectangle
+ * @Short_Description: Simple box operations
+ */
 
 /* 
  * Copyright (C) 2005, 2006 Elijah Newren

src/core/display.c

@@ -1,7 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* Mutter X display handler */
-
 /* 
  * Copyright (C) 2001 Havoc Pennington
  * Copyright (C) 2002, 2003, 2004 Red Hat, Inc.
@@ -24,9 +22,10 @@
  * 02111-1307, USA.
  */
 
-/*
- * SECTION:MetaDisplay
- * @short_description: Handles operations on an X display.
+/**
+ * SECTION:display
+ * @title: MetaDisplay
+ * @short_description: Mutter X display handler
  *
  * The display is represented as a #MetaDisplay struct.
  */

src/core/errors.c

@@ -1,7 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* Mutter X error handling */
-
 /* 
  * Copyright (C) 2001 Havoc Pennington, error trapping inspired by GDK
  * code copyrighted by the GTK team.
@@ -22,6 +20,12 @@
  * 02111-1307, USA.
  */
 
+/**
+ * SECTION:errors
+ * @title: Errors
+ * @short_description: Mutter X error handling
+ */
+
 #include <config.h>
 #include <meta/errors.h>
 #include "display-private.h"

src/core/group.c

@@ -1,7 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* Mutter window groups */
-
 /* 
  * Copyright (C) 2002 Red Hat Inc.
  * Copyright (C) 2003 Rob Adams
@@ -22,6 +20,13 @@
  * 02111-1307, USA.
  */
 
+/**
+ * SECTION:group
+ * @title: MetaGroup
+ * @short_description: Mutter window groups
+ *
+ */
+
 #include <config.h>
 #include <meta/util.h>
 #include "group-private.h"

src/core/main.c

@@ -24,6 +24,7 @@
 
 /**
  * SECTION:main
+ * @title: Main
  * @short_description: Program startup.
  *
  * Functions which parse the command-line arguments, create the display,

src/core/prefs.c

@@ -1,7 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* Mutter preferences */
-
 /* 
  * Copyright (C) 2001 Havoc Pennington, Copyright (C) 2002 Red Hat Inc.
  * Copyright (C) 2006 Elijah Newren
@@ -24,6 +22,12 @@
  * 02111-1307, USA.
  */
 
+/**
+ * SECTION:prefs
+ * @title: Preferences
+ * @short_description: Mutter preferences
+ */
+
 #include <config.h>
 #include <meta/prefs.h>
 #include "ui.h"

src/core/screen.c

@@ -1,7 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* Mutter X screen handler */
-
 /* 
  * Copyright (C) 2001, 2002 Havoc Pennington
  * Copyright (C) 2002, 2003 Red Hat Inc.
@@ -26,6 +24,12 @@
  * 02111-1307, USA.
  */
 
+/**
+ * SECTION:screen
+ * @title: MetaScreen
+ * @short_description: Mutter X screen handler
+ */
+
 #include <config.h>
 #include "screen-private.h"
 #include <meta/main.h>

src/core/util.c

@@ -1,7 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* Mutter utilities */
-
 /* 
  * Copyright (C) 2001 Havoc Pennington
  * Copyright (C) 2005 Elijah Newren
@@ -22,6 +20,12 @@
  * 02111-1307, USA.
  */
 
+/**
+ * SECTION:util
+ * @title: Utility functions
+ * @short_description: Miscellaneous utility functions
+ */
+
 #define _GNU_SOURCE
 #define _POSIX_C_SOURCE 200112L /* for fdopen() */
 

src/core/window.c

@@ -1,7 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* Mutter X managed windows */
-
 /*
  * Copyright (C) 2001 Havoc Pennington, Anders Carlsson
  * Copyright (C) 2002, 2003 Red Hat, Inc.
@@ -24,6 +22,12 @@
  * 02111-1307, USA.
  */
 
+/**
+ * SECTION:window
+ * @title: MetaWindow
+ * @short_description: Mutter X managed windows
+ */
+
 #include <config.h>
 #include "window-private.h"
 #include "boxes-private.h"

src/core/workspace.c

@@ -1,7 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* Mutter Workspaces */
-
 /* 
  * Copyright (C) 2001 Havoc Pennington
  * Copyright (C) 2003 Rob Adams
@@ -23,6 +21,17 @@
  * 02111-1307, USA.
  */
 
+/**
+ * SECTION:workspace
+ * @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 <config.h>
 #include "screen-private.h"
 #include <meta/workspace.h>

src/meta/common.h

@@ -1,7 +1,6 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* Mutter common types shared by core.h and ui.h
- *
+/*
  * PLEASE KEEP IN SYNC WITH GSETTINGS SCHEMAS!
  */
 
@@ -35,6 +34,12 @@
 #include <glib.h>
 #include <gtk/gtk.h>
 
+/**
+ * SECTION:common
+ * @Title: Common
+ * @Short_Description: Mutter common types
+ */
+
 /* This is set in stone and also hard-coded in GDK. */
 #define META_VIRTUAL_CORE_POINTER_ID 2
 #define META_VIRTUAL_CORE_KEYBOARD_ID 3

src/meta/meta-background-group.h

@@ -5,18 +5,6 @@
 
 #include <clutter/clutter.h>
 
-/**
- * MetaBackgroundGroup:
- *
- * This class is a subclass of ClutterActor with special handling for
- * MetaBackgroundActor/MetaBackgroundGroup when painting children.
- * It makes sure to only draw the parts of the backgrounds not
- * occluded by opaque windows.
- *
- * See #MetaWindowGroup for more information behind the motivation,
- * and details on implementation.
- */
-
 #define META_TYPE_BACKGROUND_GROUP            (meta_background_group_get_type ())
 #define META_BACKGROUND_GROUP(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), META_TYPE_BACKGROUND_GROUP, MetaBackgroundGroup))
 #define META_BACKGROUND_GROUP_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), META_TYPE_BACKGROUND_GROUP, MetaBackgroundGroupClass))

src/meta/workspace.h

@@ -23,17 +23,6 @@
 #ifndef META_WORKSPACE_H
 #define META_WORKSPACE_H
 
-/**
- * SECTION:workspace
- * @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>

src/ui/gradient.c

@@ -1,7 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* Metacity gradient rendering */
-
 /* 
  * Copyright (C) 2001 Havoc Pennington, 99% copied from wrlib in
  * WindowMaker, Copyright (C) 1997-2000 Dan Pascu and Alfredo Kojima
@@ -22,6 +20,12 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
  * 02111-1307, USA.  */
 
+/**
+ * SECTION:gradient
+ * @title: Gradients
+ * @short_description: Metacity gradient rendering
+ */
+
 #include <meta/gradient.h>
 #include <meta/util.h>
 #include <string.h>

src/ui/preview-widget.c

@@ -1,7 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* Metacity theme preview widget */
-
 /* 
  * Copyright (C) 2002 Havoc Pennington
  * 
@@ -21,6 +19,12 @@
  * 02111-1307, USA.
  */
 
+/**
+ * SECTION:preview-widget
+ * @title: MetaPreview
+ * @short_description: Mutter theme preview widget
+ */
+
 #define _GNU_SOURCE
 #define _XOPEN_SOURCE 600 /* for the maths routines over floats */
 

src/ui/theme.c

@@ -1,7 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* Metacity Theme Rendering */
-
 /*
  * Copyright (C) 2001 Havoc Pennington
  *
@@ -23,14 +21,17 @@
 
 /**
  * SECTION:theme
- * @short_description: Making Metacity look pretty
+ * @title: MetaTheme
+ * @short_description: Metacity Theme Rendering
  *
  * The window decorations drawn by Metacity are described by files on disk
  * known internally as "themes" (externally as "window border themes" on
  * http://art.gnome.org/themes/metacity/ or "Metacity themes"). This file
  * contains most of the code necessary to support themes; it does not
  * contain the XML parser, which is in theme-parser.c.
- *
+ */
+
+/*
  * FIXME: This is a big file with lots of different subsystems, which might
  *        be better split out into separate files.
  */