diff --git a/gdk/directfb/gdkdisplay-directfb.c b/gdk/directfb/gdkdisplay-directfb.c
index 143ff1ad8f..4feea27411 100644
--- a/gdk/directfb/gdkdisplay-directfb.c
+++ b/gdk/directfb/gdkdisplay-directfb.c
@@ -57,9 +57,8 @@ const GOptionEntry _gdk_windowing_args[] =
   { NULL}
 };
 
-/**
-  Main entry point for gdk in 2.6 args are parsed
-**/
+/* Main entry point for gdk in 2.6 args are parsed
+ */
 GdkDisplay * gdk_display_open (const gchar *display_name)
 {
   IDirectFB              *directfb;
diff --git a/gdk/directfb/gdkmain-directfb.c b/gdk/directfb/gdkmain-directfb.c
index 8172d47390..51ccc014a8 100644
--- a/gdk/directfb/gdkmain-directfb.c
+++ b/gdk/directfb/gdkmain-directfb.c
@@ -59,9 +59,8 @@
 void
 _gdk_windowing_init (void)
 {
-  /** 
-    Not that usable called before parse_args
-  **/
+  /* Not that usable called before parse_args
+   */
 }
 
 void
diff --git a/gdk/directfb/gdkwindow-directfb.c b/gdk/directfb/gdkwindow-directfb.c
index af0df3f135..efd83d5de3 100644
--- a/gdk/directfb/gdkwindow-directfb.c
+++ b/gdk/directfb/gdkwindow-directfb.c
@@ -1640,9 +1640,8 @@ gdk_directfb_window_clear_area (GdkWindow *window,
 
   impl = GDK_DRAWABLE_IMPL_DIRECTFB (private->impl);
 
-  /**
-	Follow XClearArea definition for zero height width
-  **/
+  /* Follow XClearArea definition for zero height width
+   */
   if( width == 0 )
 		width = impl->width-x;
   if( height == 0 )
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index 7599f20894..f9b94cf114 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -446,6 +446,19 @@ gdk_window_class_init (GdkWindowObjectClass *klass)
   quark_pointer_window = g_quark_from_static_string ("gtk-pointer-window");
 
 
+  /**
+   * GdkWindow::pick-embedded-child:
+   * @window: the window on which the signal is emitted
+   * @x: x coordinate in the window
+   * @y: y coordinate in the window
+   *
+   * The ::pick-embedded-child signal is emitted to find an embedded
+   * child at the given position.
+   *
+   * Returns: the GdkWindow of the embedded child at @x, @y, or %NULL
+   *
+   * Since: 2.18
+   */
   signals[PICK_EMBEDDED_CHILD] =
     g_signal_new (g_intern_static_string ("pick-embedded-child"),
 		  G_OBJECT_CLASS_TYPE (object_class),
@@ -457,6 +470,20 @@ gdk_window_class_init (GdkWindowObjectClass *klass)
 		  2,
 		  G_TYPE_DOUBLE,
 		  G_TYPE_DOUBLE);
+
+  /**
+   * GdkWindow::to-embedder:
+   * @window: the offscreen window on which the signal is emitted
+   * @offscreen-x: x coordinate in the offscreen window
+   * @offscreen-y: y coordinate in the offscreen window
+   * @embedder-x: return location for the x coordinate in the embedder window
+   * @embedder-y: return location for the y coordinate in the embedder window
+   *
+   * The ::to-embedder signal is emitted to translate coordinates
+   * in an offscreen window to its embedder.
+   *
+   * Since: 2.18
+   */
   signals[TO_EMBEDDER] =
     g_signal_new (g_intern_static_string ("to-embedder"),
 		  G_OBJECT_CLASS_TYPE (object_class),
@@ -470,6 +497,20 @@ gdk_window_class_init (GdkWindowObjectClass *klass)
 		  G_TYPE_DOUBLE,
 		  G_TYPE_POINTER,
 		  G_TYPE_POINTER);
+
+  /**
+   * GdkWindow::from-embedder:
+   * @window: the offscreen window on which the signal is emitted
+   * @embedder-x: x coordinate in the embedder window
+   * @embedder-y: y coordinate in the embedder window
+   * @offscreen-x: return location for the x coordinate in the offscreen window
+   * @offscreen-y: return location for the y coordinate in the offscreen window
+   *
+   * The ::from-embedder signal is emitted to translate coordinates
+   * in the embedder of an offscreen window to the offscreen window.
+   *
+   * Since: 2.18
+   */
   signals[FROM_EMBEDDER] =
     g_signal_new (g_intern_static_string ("from-embedder"),
 		  G_OBJECT_CLASS_TYPE (object_class),