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

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

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>