diff --git a/ChangeLog b/ChangeLog
index 20b729795..b15e4e5d5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2007-10-15  Matthew Allum  <mallum@openedhand.com>
+
+	* clutter/clutter-actor.c:
+	More events documentation.
+
+	* clutter/clutter-event.c:
+	* clutter/clutter-event.h:
+	Add synthetic flag and make put_event use it 
+	(via modded patch from pippin)
+
+	* clutter/clutter-main.c: (clutter_do_event):
+	dont use put event anymore when pushing enter/leave events.
+
 2007-10-15  Emmanuele Bassi  <ebassi@openedhand.com>
 
 	* clutter/pango/Makefile.am: Compile with the debug flags, if
diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index ac50c732f..ed73ff68d 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -38,6 +38,8 @@
  * <orderedlist>
  *   <listitem><para>Actors emit pointer events if set reactive, see
  *   clutter_actor_set_reactive()</para></listitem>
+ *   <listitem><para>Events are handled by connecting signal handlers to
+ *   the numerous event signal types.</para></listitem>
  *   <listitem><para>Event handlers must return %TRUE if they handled
  *   the event and wish to block the event emission chain; and %FALSE
  *   if the emission chain must continue</para></listitem>
@@ -46,10 +48,15 @@
  *   <listitem><para>Motion events (motion, enter, leave) are only emitted
  *   per actor if clutter_enable_motion_events() was called with %TRUE. If
  *   set to %FALSE (the default) then only the stage emits motion
- *   events</para></listitem>
- *   <listitem><para>Once emitted, an event has two phases: capture
- *   and bubble</para></listitem>
- * </orderedlist>
+ *   events (no enter or leave events).</para></listitem>
+ *   <listitem><para>Once emitted, an event emmision chain has two
+ *   phases: capture and bubble. A emitted event starts in the capture
+ *   phase beginning at the stage and transversing child actors until
+ *   the event source actor is reached. The emmision then enters the bubble
+ *   phase transversing back up via parents to the stage. An event
+ *   handler can abort this chain at point by returning
+ *   %TRUE.</para></listitem> 
+ *   </orderedlist>
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/clutter/clutter-event.c b/clutter/clutter-event.c
index 2b13033a9..3a0409bb3 100644
--- a/clutter/clutter-event.c
+++ b/clutter/clutter-event.c
@@ -439,19 +439,24 @@ clutter_event_peek (void)
  * clutter_event_put:
  * @event: a #ClutterEvent
  *
- * Puts a copy of the event on the back on the event queue. 
+ * Puts a copy of the event on the back of the event queue.
+ * The event will have the #CLUTTER_EVENT_FLAG_SYNTHETIC flag set. 
  *
- * Since: 0.4
+ * Since: 0.6
  */
 void
 clutter_event_put (ClutterEvent *event)
 {
   ClutterMainContext *context = clutter_context_get_default ();
+  ClutterEvent       *event_copy;
 
   /* FIXME: check queue is valid */
   g_return_if_fail (context != NULL);
 
-  g_queue_push_head (context->events_queue, clutter_event_copy (event));
+  event_copy = clutter_event_copy (event);
+  event_copy->any.flags |= CLUTTER_EVENT_FLAG_SYNTHETIC;
+
+  g_queue_push_head (context->events_queue, event_copy);
 }
 
 /**
diff --git a/clutter/clutter-event.h b/clutter/clutter-event.h
index 351ffa7a7..314b395c7 100644
--- a/clutter/clutter-event.h
+++ b/clutter/clutter-event.h
@@ -52,7 +52,7 @@ typedef enum {
 } ClutterModifierType;
 
 typedef enum {
-  CLUTTER_EVENT_FLAG_COOKED = 1 << 0,
+  CLUTTER_EVENT_FLAG_SYNTHETIC = 1 << 0,
 } ClutterEventFlags;
 
 typedef enum 
diff --git a/clutter/clutter-main.c b/clutter/clutter-main.c
index 58d9eae66..47c69ac20 100644
--- a/clutter/clutter-main.c
+++ b/clutter/clutter-main.c
@@ -1310,7 +1310,8 @@ clutter_do_event (ClutterEvent *event)
 		    /* unref in free  */
 		    cev.crossing.related = g_object_ref (actor);
 
-		    clutter_event_put (&cev); /* copys */
+		    g_queue_push_head (context->events_queue, 
+				       clutter_event_copy (&cev));
 
 		    cev.crossing.type    = CLUTTER_ENTER;
 		    cev.crossing.time    = event->any.time;
@@ -1320,7 +1321,8 @@ clutter_do_event (ClutterEvent *event)
 		    cev.crossing.source  = actor;
 		    cev.crossing.related = g_object_ref (motion_last_actor);
 
-		    clutter_event_put (&cev);
+		    g_queue_push_head (context->events_queue, 
+				       clutter_event_copy (&cev));
 		  }
 	      }
 	    motion_last_actor = actor;