diff --git a/ChangeLog b/ChangeLog
index 02e8c4da6..3fe4be576 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2008-04-22  Thomas Thurman  <tthurman@gnome.org>
+
+        * src/core/effects.c: a few comments
+
 2008-04-10  Lucas Rocha  <lucasr@gnome.org>
 
 	* src/Makefile.am: no need to create a symlink to .desktop file in
diff --git a/src/core/effects.c b/src/core/effects.c
index 45032d9f8..830c51e97 100644
--- a/src/core/effects.c
+++ b/src/core/effects.c
@@ -21,6 +21,16 @@
  * 02111-1307, USA.
  */
 
+
+/**
+ * \file effects.c "Special effects" other than compositor effects.
+ * 
+ * Before we had a serious compositor, we supported swooping
+ * rectangles for minimising and so on.  These are still supported
+ * today, even when the compositor is enabled.
+ */
+
+
 #include <config.h>
 #include "effects.h"
 #include "display.h"
@@ -256,14 +266,15 @@ update_wireframe_window (MetaDisplay         *display,
 #endif
 }
 
+/**
+ * A hack to force the X server to synchronize with the
+ * graphics hardware.
+ */
 static void
 graphics_sync (BoxAnimationContext *context)
 {
   XImage *image;
   
-  /* A hack to force the X server to synchronize with the
-   * graphics hardware
-   */
   image = XGetImage (context->screen->display->xdisplay,
 		     context->screen->xroot,
 		     0, 0, 1, 1,