GNOME.org
 

[clutter] docs: Improve more deprecation notices

commit fefc2b53210d18ee62153631f78a048127119e66
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Mar 5 16:39:01 2015 +0000

    docs: Improve more deprecation notices

 clutter/deprecated/clutter-alpha.c        |   38 ++++++++++++++++------------
 clutter/deprecated/clutter-animator.c     |    4 ++-
 clutter/deprecated/clutter-behaviour.c    |   13 ++++------
 clutter/deprecated/clutter-fixed.h        |    3 +-
 clutter/deprecated/clutter-frame-source.c |    8 +++---
 clutter/deprecated/clutter-group.c        |    7 ++++-
 clutter/deprecated/clutter-media.c        |    3 +-
 clutter/deprecated/clutter-shader.c       |    2 +-
 clutter/deprecated/clutter-state.c        |    5 +++-
 clutter/deprecated/clutter-timeout-pool.c |    6 ++--
 10 files changed, 51 insertions(+), 38 deletions(-)
---
diff --git a/clutter/deprecated/clutter-alpha.c b/clutter/deprecated/clutter-alpha.c
index def8ec5..7305acf 100644
--- a/clutter/deprecated/clutter-alpha.c
+++ b/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
- * #ClutterTimeline:progress-mode property.
+ * #ClutterAlpha is deprecated since Clutter 1.12. #ClutterTimeline and
+ * 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)
diff --git a/clutter/deprecated/clutter-animator.c b/clutter/deprecated/clutter-animator.c
index 4a4cf62..0c38811 100644
--- a/clutter/deprecated/clutter-animator.c
+++ b/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
  *
diff --git a/clutter/deprecated/clutter-behaviour.c b/clutter/deprecated/clutter-behaviour.c
index 9551188..fe85d61 100644
--- a/clutter/deprecated/clutter-behaviour.c
+++ b/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">
- *   <title>Effects of alpha functions on a path</title>
- *   <graphic fileref="path-alpha-func.png" format="PNG"/>
- * </figure>
+ * ![](path-alpha-func.png)
  *
  * 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
- * 1.6. You should see <link linkend="migrating-ClutterBehaviour">the
- * migration guide</link> for more information on migrating code from using
- * the #ClutterBehaviour API to the animation framework API.
+ * #ClutterBehaviour and its sub-classes have been discouraged sing Clutter
+ * 1.0, and formally deprecated since Clutter 1.6. You should use the
+ * [implicit animation][clutter-actor-animation] support inside #ClutterActor
+ * if you still have code using #ClutterBehaviour.
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/clutter/deprecated/clutter-fixed.h b/clutter/deprecated/clutter-fixed.h
index 215e626..98e0e1a 100644
--- a/clutter/deprecated/clutter-fixed.h
+++ b/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
 {
diff --git a/clutter/deprecated/clutter-frame-source.c b/clutter/deprecated/clutter-frame-source.c
index e0a82a2..bd9583d 100644
--- a/clutter/deprecated/clutter-frame-source.c
+++ b/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,
diff --git a/clutter/deprecated/clutter-group.c b/clutter/deprecated/clutter-group.c
index 5afaf2b..90b3504 100644
--- a/clutter/deprecated/clutter-group.c
+++ b/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
diff --git a/clutter/deprecated/clutter-media.c b/clutter/deprecated/clutter-media.c
index bfa43d8..c43b832 100644
--- a/clutter/deprecated/clutter-media.c
+++ b/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
diff --git a/clutter/deprecated/clutter-shader.c b/clutter/deprecated/clutter-shader.c
index 8e50c88..da0024b 100644
--- a/clutter/deprecated/clutter-shader.c
+++ b/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
diff --git a/clutter/deprecated/clutter-state.c b/clutter/deprecated/clutter-state.c
index f482de2..2f919a1 100644
--- a/clutter/deprecated/clutter-state.c
+++ b/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
  *
diff --git a/clutter/deprecated/clutter-timeout-pool.c b/clutter/deprecated/clutter-timeout-pool.c
index ad2b313..a220a3a 100644
--- a/clutter/deprecated/clutter-timeout-pool.c
+++ b/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,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]