From fefc2b53210d18ee62153631f78a048127119e66 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Thu, 5 Mar 2015 16:39:01 +0000 Subject: [PATCH] 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 def8ec532..7305acfc5 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 4a4cf6283..0c388118d 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 95511880d..fe85d6118 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: * - *
- * Effects of alpha functions on a path - * - *
+ * ![](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 the - * migration guide 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 215e6260e..98e0e1a74 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 e0a82a2b0..bd9583dac 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 5afaf2b6c..90b3504f4 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 bfa43d802..c43b83263 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 8e50c88d5..da0024ba3 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 f482de2ae..2f919a1d7 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 ad2b31368..a220a3a61 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,