docs: Improve more deprecation notices

clutter/deprecated/clutter-alpha.c

@@ -64,8 +64,8 @@
  *
  * #ClutterAlpha is available since Clutter 0.2.
  *
- * #ClutterAlpha is deprecated since Clutter 1.12; use #ClutterTimeline and the
+ * #ClutterAlpha is deprecated since Clutter 1.12. #ClutterTimeline and
- * #ClutterTimeline:progress-mode property.
+ * the #ClutterTimeline:progress-mode property replace this whole class.
  *
  * ## ClutterAlpha custom properties for #ClutterScript
  *
@@ -357,7 +357,8 @@ clutter_alpha_class_init (ClutterAlphaClass *klass)
    * one unit in each direction, so the valid interval is -1.0 to 2.0.
    *
    * Since: 0.2
-   * Deprecated: 1.12
+   * Deprecated: 1.12: Use #ClutterTimeline::new-frame and
+   *   clutter_timeline_get_progress() instead
    */
   obj_props[PROP_ALPHA] =
     g_param_spec_double ("alpha",
@@ -379,7 +380,7 @@ clutter_alpha_class_init (ClutterAlphaClass *klass)
    * will be used.
    *
    * Since: 1.0
-   * Deprecated: 1.12
+   * Deprecated: 1.12: Use #ClutterTimeline:progress-mode
    */
   obj_props[PROP_MODE] =
     g_param_spec_ulong ("mode",
@@ -412,7 +413,7 @@ clutter_alpha_init (ClutterAlpha *self)
  *
  * Since: 0.2
  *
- * Deprecated: 1.12
+ * Deprecated: 1.12: Use clutter_timeline_get_progress()
  */
 gdouble
 clutter_alpha_get_alpha (ClutterAlpha *alpha)
@@ -503,7 +504,7 @@ clutter_alpha_set_closure_internal (ClutterAlpha *alpha,
  *
  * Since: 0.8
  *
- * Deprecated: 1.12
+ * Deprecated: 1.12: Use clutter_timeline_set_progress_func()
  */
 void
 clutter_alpha_set_closure (ClutterAlpha *alpha,
@@ -537,7 +538,7 @@ clutter_alpha_set_closure (ClutterAlpha *alpha,
  *
  * Since: 0.2
  *
- * Deprecated: 1.12
+ * Deprecated: 1.12: Use clutter_timeline_set_progress_func()
  */
 void
 clutter_alpha_set_func (ClutterAlpha    *alpha,
@@ -580,7 +581,7 @@ clutter_alpha_set_func (ClutterAlpha    *alpha,
  *
  * Since: 0.2
  *
- * Deprecated: 1.12
+ * Deprecated: 1.12: Use #ClutterTimeline directly
  */
 void
 clutter_alpha_set_timeline (ClutterAlpha    *alpha,
@@ -628,7 +629,7 @@ clutter_alpha_set_timeline (ClutterAlpha    *alpha,
  *
  * Since: 0.2
  *
- * Deprecated: 1.12
+ * Deprecated: 1.12: Use #ClutterTimeline directlry
  */
 ClutterTimeline *
 clutter_alpha_get_timeline (ClutterAlpha *alpha)
@@ -653,7 +654,7 @@ clutter_alpha_get_timeline (ClutterAlpha *alpha)
  *
  * Since: 0.2
  *
- * Deprecated: 1.12
+ * Deprecated: 1.12: Use #ClutterTimeline instead
  */
 ClutterAlpha *
 clutter_alpha_new (void)
@@ -675,7 +676,7 @@ clutter_alpha_new (void)
  *
  * Since: 1.0
  *
- * Deprecated: 1.12
+ * Deprecated: 1.12: Use #ClutterTimeline instead
  */
 ClutterAlpha *
 clutter_alpha_new_full (ClutterTimeline *timeline,
@@ -708,7 +709,7 @@ clutter_alpha_new_full (ClutterTimeline *timeline,
  *
  * Since: 1.0
  *
- * Deprecated: 1.12
+ * Deprecated: 1.12: Use #ClutterTimeline instead
  */
 ClutterAlpha *
 clutter_alpha_new_with_func (ClutterTimeline  *timeline,
@@ -738,7 +739,7 @@ clutter_alpha_new_with_func (ClutterTimeline  *timeline,
  *
  * Since: 1.0
  *
- * Deprecated: 1.12
+ * Deprecated: 1.12: Use #ClutterTimeline instead
  */
 gulong
 clutter_alpha_get_mode (ClutterAlpha *alpha)
@@ -787,7 +788,8 @@ clutter_alpha_easing_func (ClutterAlpha *alpha,
  *
  * Since: 1.0
  *
- * Deprecated: 1.12
+ * Deprecated: 1.12: Use #ClutterTimeline and
+ *   clutter_timeline_set_progress_mode() instead
  */
 void
 clutter_alpha_set_mode (ClutterAlpha *alpha,
@@ -896,7 +898,9 @@ register_alpha_internal (AlphaData *alpha_data)
  *
  * Since: 1.0
  *
- * Deprecated: 1.12
+ * Deprecated: 1.12: There is no direct replacement for this
+ *   function. Use clutter_timeline_set_progress_func() on each
+ *   specific #ClutterTimeline instance
  */
 gulong
 clutter_alpha_register_func (ClutterAlphaFunc func,
@@ -929,7 +933,9 @@ clutter_alpha_register_func (ClutterAlphaFunc func,
  *
  * Since: 1.0
  *
- * Deprecated: 1.12
+ * Deprecated: 1.12: There is no direct replacement for this
+ *   function. Use clutter_timeline_set_progress_func() on each
+ *   specific #ClutterTimeline instance
  */
 gulong
 clutter_alpha_register_closure (GClosure *closure)

clutter/deprecated/clutter-animator.c

@@ -39,7 +39,9 @@
  *
  * #ClutterAnimator is available since Clutter 1.2
  *
- * #ClutterAnimator has been deprecated in Clutter 1.12
+ * #ClutterAnimator has been deprecated in Clutter 1.12. If you
+ * want to combine multiple transitions using key frames, use
+ * #ClutterKeyframeTransition and #ClutterTransitionGroup instead.
  *
  * ## Key Frames
  *

clutter/deprecated/clutter-behaviour.c

@@ -47,10 +47,7 @@
  * #ClutterBehaviour implementation it is possible to take the
  * #ClutterBehaviourPath as an example:
  *
- * <figure id="behaviour-path-alpha">
+ * ![](path-alpha-func.png)
- *   <title>Effects of alpha functions on a path</title>
- *   <graphic fileref="path-alpha-func.png" format="PNG"/>
- * </figure>
  *
  * The actors position between the path's end points directly correlates
  * to the #ClutterAlpha's current alpha value driving the behaviour. With
@@ -67,10 +64,10 @@
  *
  * #ClutterBehaviour is available since Clutter 0.2.
  *
- * #ClutterBehaviour and its sub-classes have been deprecated since Clutter
+ * #ClutterBehaviour and its sub-classes have been discouraged sing Clutter
- * 1.6. You should see <link linkend="migrating-ClutterBehaviour">the
+ * 1.0, and formally deprecated since Clutter 1.6. You should use the
- * migration guide</link> for more information on migrating code from using
+ * [implicit animation][clutter-actor-animation] support inside #ClutterActor
- * the #ClutterBehaviour API to the animation framework API.
+ * if you still have code using #ClutterBehaviour.
  */
 
 #ifdef HAVE_CONFIG_H

clutter/deprecated/clutter-fixed.h

@@ -62,7 +62,8 @@ typedef struct _ClutterParamSpecFixed   ClutterParamSpecFixed;
  *
  * Since: 0.8
  *
- * Deprecated: Use #GParamSpecInt instead
+ * Deprecated: 1.10: Do not use fixed-point values in public
+ *   API. If you must, use #GParamSpecInt instead.
  */
 struct _ClutterParamSpecFixed
 {

clutter/deprecated/clutter-frame-source.c

@@ -89,7 +89,7 @@ static GSourceFuncs clutter_frame_source_funcs =
  *
  * Since: 0.8
  *
- * Deprecated: 1.6
+ * Deprecated: 1.6: There is no direct replacement for this API.
  */
 guint
 clutter_frame_source_add_full (gint           priority,
@@ -130,7 +130,7 @@ clutter_frame_source_add_full (gint           priority,
  *
  * Since: 0.8
  *
- * Deprecated: 1.6
+ * Deprecated: 1.6: There is no direct replacement for this API
  */
 guint
 clutter_frame_source_add (guint          fps,
@@ -211,7 +211,7 @@ clutter_frame_source_dispatch (GSource     *source,
  *
  * Since: 0.8
  *
- * Deprecated: 1.6
+ * Deprecated: 1.6: There is no direct replacement for this API
  */
 guint
 clutter_threads_add_frame_source_full (gint           priority,
@@ -247,7 +247,7 @@ clutter_threads_add_frame_source_full (gint           priority,
  *
  * Since: 0.8
  *
- * Deprecated: 1.6
+ * Deprecated: 1.6: There is no direct replacement for this API
  */
 guint
 clutter_threads_add_frame_source (guint       fps,

clutter/deprecated/clutter-group.c

@@ -41,7 +41,10 @@
  * explicitly set the size of the #ClutterGroup and then use the
  * #ClutterActor:clip-to-allocation property.
  *
- * Deprecated: 1.10: Use #ClutterActor instead.
+ * #ClutterGroup as a concrete class has been superceded by #ClutterActor
+ * since Clutter 1.10. The type itself is not deprecated as it is used by
+ * #ClutterStage. You should instantiate #ClutterActor and use its API to
+ * manage child actors.
  */
 
 #ifdef HAVE_CONFIG_H
@@ -463,7 +466,7 @@ clutter_group_init (ClutterGroup *self)
    *
    * XXX - these so-called "optimizations" are insane and should have never
    * been used. they introduce some weird behaviour that breaks invariants
-   * and has to be explicitly worked around.
+   * and have to be explicitly worked around.
    *
    * this flag was set by the ClutterFixedLayout, but since that layout
    * manager is now the default for ClutterActor, we set the flag explicitly

clutter/deprecated/clutter-media.c

@@ -35,7 +35,8 @@
  *
  * #ClutterMedia is available since Clutter 0.2
  *
- * #ClutterMedia is deprecated since Clutter 1.12
+ * #ClutterMedia is deprecated since Clutter 1.12. Use the Clutter-GStreamer
+ * API directly instead.
  */
 
 #ifdef HAVE_CONFIG_H

clutter/deprecated/clutter-shader.c

@@ -38,7 +38,7 @@
  * #ClutterShader is available since Clutter 0.6.
  *
  * #ClutterShader is deprecated since Clutter 1.8; use #ClutterShaderEffect
- * in newly written code.
+ * in newly written code, instead.
  */
 
 #ifdef HAVE_CONFIG_H

clutter/deprecated/clutter-state.c

@@ -33,7 +33,10 @@
  *
  * #ClutterState is available since Clutter 1.4.
  *
- * #ClutterState has been deprecated in Clutter 1.12.
+ * #ClutterState has been deprecated in Clutter 1.12. There is no direct
+ * replacement for this API, but it's highly suggested you use a combination
+ * of [implicit transitions][clutter-actor-animation] and explicit transitions
+ * using #ClutterTransition and its subclasses.
  *
  * ## Using ClutterState
  *

clutter/deprecated/clutter-timeout-pool.c

@@ -381,7 +381,7 @@ clutter_timeout_pool_finalize (GSource *source)
  *
  * Since: 0.4
  *
- * Deprecated: 1.6
+ * Deprecated: 1.6: There is no direct replacement for this API
  */
 ClutterTimeoutPool *
 clutter_timeout_pool_new (gint priority)
@@ -437,7 +437,7 @@ clutter_timeout_pool_new (gint priority)
  *
  * Since: 0.4
  *
- * Deprecated: 1.6
+ * Deprecated: 1.6: There is no direct replacement for this API
  */
 guint
 clutter_timeout_pool_add (ClutterTimeoutPool *pool,
@@ -474,7 +474,7 @@ clutter_timeout_pool_add (ClutterTimeoutPool *pool,
  *
  * Since: 0.4
  *
- * Deprecated: 1.6
+ * Deprecated: 1.6: There is no direct replacement for this API
  */
 void
 clutter_timeout_pool_remove (ClutterTimeoutPool *pool,