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

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

25 files changed, 144 insertions, 69 deletions

diff --git a/doc/reference/meta-sections.txt b/doc/reference/meta-sections.txt
index 176a6a6a8..754fe9e82 100644
--- a/doc/reference/meta-sections.txt
+++ b/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
diff --git a/src/compositor/meta-background-actor.c b/src/compositor/meta-background-actor.c
index 506091993..11a044a46 100644
--- a/src/compositor/meta-background-actor.c
+++ b/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>
diff --git a/src/compositor/meta-background-group.c b/src/compositor/meta-background-group.c
index 5bf6d4a93..e413a8e12 100644
--- a/src/compositor/meta-background-group.c
+++ b/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"
diff --git a/src/compositor/meta-background.c b/src/compositor/meta-background.c
index 880b53df1..fd2d1d271 100644
--- a/src/compositor/meta-background.c
+++ b/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>
diff --git a/src/compositor/meta-plugin.c b/src/compositor/meta-plugin.c
index 8aa3f1cac..a7ee1137b 100644
--- a/src/compositor/meta-plugin.c
+++ b/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>
diff --git a/src/compositor/meta-shadow-factory.c b/src/compositor/meta-shadow-factory.c
index e36bf2085..dbda21a4e 100644
--- a/src/compositor/meta-shadow-factory.c
+++ b/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>
diff --git a/src/compositor/meta-shaped-texture.c b/src/compositor/meta-shaped-texture.c
index e6715b02c..c6239c9d2 100644
--- a/src/compositor/meta-shaped-texture.c
+++ b/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>
diff --git a/src/compositor/meta-window-actor.c b/src/compositor/meta-window-actor.c
index 58b141e1f..5c667b060 100644
--- a/src/compositor/meta-window-actor.c
+++ b/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>
diff --git a/src/core/barrier.c b/src/core/barrier.c
index b4e45ebfa..80ac3cd9b 100644
--- a/src/core/barrier.c
+++ b/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>
diff --git a/src/core/boxes.c b/src/core/boxes.c
index 433bfa7f3..3c4f4446d 100644
--- a/src/core/boxes.c
+++ b/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
diff --git a/src/core/display.c b/src/core/display.c
index 5c0de6257..f4f7e6325 100644
--- a/src/core/display.c
+++ b/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.
  */
diff --git a/src/core/errors.c b/src/core/errors.c
index df44cb207..4028133c1 100644
--- a/src/core/errors.c
+++ b/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"
diff --git a/src/core/group.c b/src/core/group.c
index 54f42f61f..8655d48a1 100644
--- a/src/core/group.c
+++ b/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"
diff --git a/src/core/main.c b/src/core/main.c
index 7054d97e8..4bec3d260 100644
--- a/src/core/main.c
+++ b/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,
diff --git a/src/core/prefs.c b/src/core/prefs.c
index 13ace779a..452126451 100644
--- a/src/core/prefs.c
+++ b/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"
diff --git a/src/core/screen.c b/src/core/screen.c
index 48f020281..938606f7d 100644
--- a/src/core/screen.c
+++ b/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>
diff --git a/src/core/util.c b/src/core/util.c
index 8f10bbbc7..2e218760e 100644
--- a/src/core/util.c
+++ b/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() */
 
diff --git a/src/core/window.c b/src/core/window.c
index 073bde91f..d3de779b2 100644
--- a/src/core/window.c
+++ b/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"
diff --git a/src/core/workspace.c b/src/core/workspace.c
index 0e2d1bb11..71f78a120 100644
--- a/src/core/workspace.c
+++ b/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>
diff --git a/src/meta/common.h b/src/meta/common.h
index 8af3e078a..98f2ad781 100644
--- a/src/meta/common.h
+++ b/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
diff --git a/src/meta/meta-background-group.h b/src/meta/meta-background-group.h
index edd3e3127..9997b739e 100644
--- a/src/meta/meta-background-group.h
+++ b/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))
diff --git a/src/meta/workspace.h b/src/meta/workspace.h
index 7e0ce3cd7..972177060 100644
--- a/src/meta/workspace.h
+++ b/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>
diff --git a/src/ui/gradient.c b/src/ui/gradient.c
index d6e872fa4..6017f65a6 100644
--- a/src/ui/gradient.c
+++ b/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>
diff --git a/src/ui/preview-widget.c b/src/ui/preview-widget.c
index 8e03766bd..799a0867c 100644
--- a/src/ui/preview-widget.c
+++ b/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 */
 
diff --git a/src/ui/theme.c b/src/ui/theme.c
index bf57016fb..e1543cf29 100644
--- a/src/ui/theme.c
+++ b/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.
  */