diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 270126f91..eaf2ef88b 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -544,6 +544,9 @@
  * unnecessary (and potentially expensive) state changes.
  *
  * Since: 0.2
+ *
+ * Deprecated: 1.24: Use clutter_actor_is_mapped() or the #ClutterActor:mapped
+ *   property instead of this macro.
  */
 
 /**
@@ -566,6 +569,9 @@
  * must be realized.
  *
  * Since: 0.2
+ *
+ * Deprecated: 1.24: Use clutter_actor_is_realized() or the #ClutterActor:realized
+ *   property instead of this macro.
  */
 
 /**
@@ -580,6 +586,9 @@
  * parents is a toplevel stage; see also %CLUTTER_ACTOR_IS_MAPPED.
  *
  * Since: 0.2
+ *
+ * Deprecated: 1.24: Use clutter_actor_is_visible() or the #ClutterActor:visible
+ *   property instead of this macro.
  */
 
 /**
@@ -591,6 +600,9 @@
  * Only reactive actors will receive event-related signals.
  *
  * Since: 0.6
+ *
+ * Deprecated: 1.24: Use clutter_actor_get_reactive() or the
+ *   #ClutterActor:reactive property instead of this macro.
  */
 
 #include "config.h"
diff --git a/clutter/clutter-actor.h b/clutter/clutter-actor.h
index a11fbb944..a71ca270d 100644
--- a/clutter/clutter-actor.h
+++ b/clutter/clutter-actor.h
@@ -54,6 +54,10 @@ G_BEGIN_DECLS
  * @f: the #ClutterActorFlags to set
  *
  * Sets the given flags on a #ClutterActor
+ *
+ * Deprecated: 1.24: Changing flags directly is heavily discouraged in
+ *   newly written code. #ClutterActor will take care of setting the
+ *   internal state.
  */
 #define CLUTTER_ACTOR_SET_FLAGS(a,f)    (((ClutterActor*)(a))->flags |= (f))
 
@@ -63,6 +67,10 @@ G_BEGIN_DECLS
  * @f: the #ClutterActorFlags to unset
  *
  * Unsets the given flags on a #ClutterActor
+ *
+ * Deprecated: 1.24: Changing flags directly is heavily discouraged in
+ *   newly written code. #ClutterActor will take care of unsetting the
+ *   internal state.
  */
 #define CLUTTER_ACTOR_UNSET_FLAGS(a,f)  (((ClutterActor*)(a))->flags &= ~(f))