Added documentation section titles

src/compositor/compositor.c

@@ -1,5 +1,61 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
+/**
+ * SECTION:compositor
+ * @title: MetaCompositor
+ * @short_Description: Compositor API
+ *
+ * At a high-level, a window is not-visible or visible. When a
+ * window is added (with meta_compositor_add_window()) it is not visible.
+ * meta_compositor_show_window() indicates a transition from not-visible to
+ * visible. Some of the reasons for this:
+ *
+ * - Window newly created
+ * - Window is unminimized
+ * - Window is moved to the current desktop
+ * - Window was made sticky
+ *
+ * meta_compositor_hide_window() indicates that the window has transitioned from
+ * visible to not-visible. Some reasons include:
+ *
+ * - Window was destroyed
+ * - Window is minimized
+ * - Window is moved to a different desktop
+ * - Window no longer sticky.
+ *
+ * Note that combinations are possible - a window might have first
+ * been minimized and then moved to a different desktop. The 'effect' parameter
+ * to meta_compositor_show_window() and meta_compositor_hide_window() is a hint
+ * as to the appropriate effect to show the user and should not
+ * be considered to be indicative of a state change.
+ *
+ * When the active workspace is changed, meta_compositor_switch_workspace() is
+ * called first, then meta_compositor_show_window() and
+ * meta_compositor_hide_window() are called individually for each window
+ * affected, with an effect of META_COMP_EFFECT_NONE.
+ * If hiding windows will affect the switch workspace animation, the
+ * compositor needs to delay hiding the windows until the switch
+ * workspace animation completes.
+ *
+ * meta_compositor_maximize_window() and meta_compositor_unmaximize_window()
+ * are transitions within the visible state. The window is resized __before__
+ * the call, so it may be necessary to readjust the display based on the
+ * old_rect to start the animation.
+ *
+ * # Containers #
+ *
+ * There's two containers in the stage that are used to place window actors, here
+ * are listed in the order in which they are painted:
+ *
+ * - window group, accessible with meta_get_window_group_for_screen()
+ * - top window group, accessible with meta_get_top_window_group_for_screen()
+ *
+ * Muffin will place actors representing windows in the window group, except for
+ * override-redirect windows (ie. popups and menus) which will be placed in the
+ * top window group.
+ */
+
+
 #include <config.h>
 
 #include <clutter/x11/clutter-x11.h>

src/compositor/meta-background-actor.c

@@ -23,6 +23,12 @@
  * 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>
 
 #define COGL_ENABLE_EXPERIMENTAL_API

src/compositor/meta-plugin.c

@@ -21,6 +21,12 @@
  * 02110-1335, 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

@@ -21,6 +21,13 @@
  * Foundation, Inc., 51 Franklin Street - Suite 500, Boston, MA
  * 02110-1335, USA.
  */
+
+/**
+ * SECTION:meta-shadow-factory
+ * @title: MetaShadowFactory
+ * @short_description: Create and cache shadow textures for arbitrary window shapes
+ */
+
 #include <config.h>
 #include <math.h>
 #include <string.h>

src/compositor/meta-shaped-texture.c

@@ -23,6 +23,12 @@
  * 02110-1335, USA.
  */
 
+/**
+ * SECTION:meta-shaped-texture
+ * @title: MetaShapedTexture
+ * @short_description: An actor to draw a masked texture.
+ */
+
 #include <config.h>
 
 #define CLUTTER_ENABLE_EXPERIMENTAL_API

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/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

@@ -25,7 +25,8 @@
  */
 
 /**
- * SECTION:MetaDisplay
+ * SECTION:display
+ * @title: MetaDisplay
  * @short_description: Handles operations on an X display.
  *
  * The display is represented as a MetaDisplay struct.

src/core/errors.c

@@ -22,6 +22,12 @@
  * 02110-1335, USA.
  */
 
+/**
+ * SECTION:errors
+ * @title: Errors
+ * @short_description: Muffin 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; -*- */
 
-/* Muffin window groups */
-
 /* 
  * Copyright (C) 2002 Red Hat Inc.
  * Copyright (C) 2003 Rob Adams
@@ -22,6 +20,14 @@
  * 02110-1335, USA.
  */
 
+/**
+ * SECTION:group
+ * @title: MetaGroup
+ * @short_description: Muffin window groups
+ *
+ */
+
+
 #include <config.h>
 #include <meta/util.h>
 #include "group-private.h"

src/core/keybindings.c

@@ -23,6 +23,12 @@
  * 02110-1335, USA.
  */
 
+/**
+ * SECTION:keybindings
+ * @title: MetaKeybinding
+ * @short_description: Key bindings
+ */
+
 #ifndef _GNU_SOURCE
 #define _GNU_SOURCE
 #endif

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

@@ -24,6 +24,12 @@
  * 02110-1335, USA.
  */
 
+/**
+ * SECTION:prefs
+ * @title: Preferences
+ * @short_description: Muffin 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; -*- */
 
-/* Muffin X screen handler */
-
 /* 
  * Copyright (C) 2001, 2002 Havoc Pennington
  * Copyright (C) 2002, 2003 Red Hat Inc.
@@ -26,6 +24,12 @@
  * 02110-1335, USA.
  */
 
+/**
+ * SECTION:screen
+ * @title: MetaScreen
+ * @short_description: Muffin X screen handler
+ */
+
 #include <config.h>
 #include "screen-private.h"
 #include <meta/main.h>

src/core/util.c

@@ -22,6 +22,12 @@
  * 02110-1335, USA.
  */
 
+/**
+ * SECTION:util
+ * @title: Utility functions
+ * @short_description: Miscellaneous utility functions
+ */
+
 #ifndef _GNU_SOURCE
 #define _GNU_SOURCE
 #endif

src/core/window.c

@@ -1,7 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/* Muffin X managed windows */
-
 /*
  * Copyright (C) 2001 Havoc Pennington, Anders Carlsson
  * Copyright (C) 2002, 2003 Red Hat, Inc.
@@ -24,6 +22,12 @@
  * 02110-1335, USA.
  */
 
+/**
+ * SECTION:window
+ * @title: MetaWindow
+ * @short_description: Muffin 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; -*- */
 
-/* Muffin Workspaces */
-
 /* 
  * Copyright (C) 2001 Havoc Pennington
  * Copyright (C) 2003 Rob Adams
@@ -23,6 +21,19 @@
  * 02110-1335, USA.
  */
 
+/**
+ * SECTION:workspace
+ * @title: MetaWorkspace
+ * @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

@@ -33,6 +33,12 @@
 #include <glib.h>
 #include <gtk/gtk.h>
 
+/**
+ * SECTION:common
+ * @title: Common
+ * @short_description: Muffin common types
+ */
+
 typedef struct _MetaResizePopup MetaResizePopup;
 
 typedef enum