docs: Update the Container interface documentation

The API reference should be more explicit about which parts of the
interface should be overridden, and which are deprecated.

clutter/clutter-container.c

@@ -67,8 +67,17 @@
  * SECTION:clutter-container
  * @short_description: An interface for container actors
  *
- * #ClutterContainer provides some common API for #ClutterActor
+ * #ClutterContainer is an interface implemented by #ClutterActor, and
- * instances containing children.
+ * it provides some common API for notifying when a child actor is added
+ * or removed, as well as the infrastructure for accessing child properties
+ * through #ClutterChildMeta.
+ *
+ * Until Clutter 1.10, the #ClutterContainer interface was also the public
+ * API for implementing container actors; this part of the interface has
+ * been deprecated: #ClutterContainer has a default implementation which
+ * defers to #ClutterActor the child addition and removal, as well as the
+ * iteration. See the documentation of #ClutterContainerIface for the list
+ * of virtual functions that should be overridden.
  */
 
 enum
@@ -360,6 +369,10 @@ container_remove_valist (ClutterContainer *container,
  * be parented to @container, which takes a reference on the actor. You
  * cannot add a #ClutterActor to more than one #ClutterContainer.
  *
+ * This function will call #ClutterContainerIface.add(), which is a
+ * deprecated virtual function. The default implementation will
+ * call clutter_actor_add_child().
+ *
  * Since: 0.4
  *
  * Deprecated: 1.10: Use clutter_actor_add_child() instead.
@@ -389,6 +402,10 @@ clutter_container_add (ClutterContainer *container,
  * @container. You cannot add a #ClutterActor to more than one
  * #ClutterContainer.
  *
+ * This function will call #ClutterContainerIface.add(), which is a
+ * deprecated virtual function. The default implementation will
+ * call clutter_actor_add_child().
+ *
  * Virtual: add
  *
  * Since: 0.4
@@ -413,6 +430,10 @@ clutter_container_add_actor (ClutterContainer *container,
  *
  * Alternative va_list version of clutter_container_add().
  *
+ * This function will call #ClutterContainerIface.add(), which is a
+ * deprecated virtual function. The default implementation will
+ * call clutter_actor_add_child().
+ *
  * Since: 0.4
  *
  * Deprecated: 1.10: Use clutter_actor_add_child() instead.
@@ -440,6 +461,10 @@ clutter_container_add_valist (ClutterContainer *container,
  * Each time an actor is removed, the "actor-removed" signal is
  * emitted by @container.
  *
+ * This function will call #ClutterContainerIface.remove(), which is a
+ * deprecated virtual function. The default implementation will call
+ * clutter_actor_remove_child().
+ *
  * Since: 0.4
  *
  * Deprecated: 1.10: Use clutter_actor_remove_child() instead.
@@ -469,6 +494,10 @@ clutter_container_remove (ClutterContainer *container,
  * yourself, using g_object_ref(). When the actor has been removed,
  * the "actor-removed" signal is emitted by @container.
  *
+ * This function will call #ClutterContainerIface.remove(), which is a
+ * deprecated virtual function. The default implementation will call
+ * clutter_actor_remove_child().
+ *
  * Virtual: remove
  *
  * Since: 0.4
@@ -493,6 +522,10 @@ clutter_container_remove_actor (ClutterContainer *container,
  *
  * Alternative va_list version of clutter_container_remove().
  *
+ * This function will call #ClutterContainerIface.remove(), which is a
+ * deprecated virtual function. The default implementation will call
+ * clutter_actor_remove_child().
+ *
  * Since: 0.4
  *
  * Deprecated: 1.10: Use clutter_actor_remove_child() instead.
@@ -555,12 +588,16 @@ clutter_container_get_children (ClutterContainer *container)
  * not iterate over "internal" children that are part of the
  * container's own implementation, if any.
  *
+ * This function calls the #ClutterContainerIface.foreach()
+ * virtual function, which has been deprecated.
+ *
  * Since: 0.4
  *
  * Deprecated: 1.10: Use clutter_actor_get_first_child() or
  *   clutter_actor_get_last_child() to retrieve the beginning of
  *   the list of children, and clutter_actor_get_next_sibling()
- *   and clutter_actor_get_previous_sibling() to iterate over it.
+ *   and clutter_actor_get_previous_sibling() to iterate over it;
+ *   alternatively, use the #ClutterActorIter API.
  */
 void
 clutter_container_foreach (ClutterContainer *container,
@@ -598,6 +635,9 @@ clutter_container_foreach (ClutterContainer *container,
  * children built in to the container itself that were never added
  * by the application.
  *
+ * This function calls the #ClutterContainerIface.foreach_with_internals()
+ * virtual function, which has been deprecated.
+ *
  * Since: 1.0
  *
  * Deprecated: 1.10: See clutter_container_foreach().
@@ -640,6 +680,10 @@ clutter_container_foreach_with_internals (ClutterContainer *container,
  *
  * Raises @actor to @sibling level, in the depth ordering.
  *
+ * This function calls the #ClutterContainerIface.raise() virtual function,
+ * which has been deprecated. The default implementation will call
+ * clutter_actor_set_child_above_sibling().
+ *
  * Virtual: raise
  *
  * Since: 0.6
@@ -707,6 +751,10 @@ clutter_container_raise_child (ClutterContainer *container,
  *
  * Lowers @actor to @sibling level, in the depth ordering.
  *
+ * This function calls the #ClutterContainerIface.lower() virtual function,
+ * which has been deprecated. The default implementation will call
+ * clutter_actor_set_child_below_sibling().
+ *
  * Virtual: lower
  *
  * Since: 0.6
@@ -1387,8 +1435,8 @@ clutter_container_child_get (ClutterContainer *container,
  * @child: a #ClutterActor
  * @pspec: a #GParamSpec
  *
- * Calls the <function>child_notify()</function> virtual function of
+ * Calls the #ClutterContainerIface.child_notify() virtual function
- * #ClutterContainer. The default implementation will emit the
+ * of #ClutterContainer. The default implementation will emit the
  * #ClutterContainer::child-notify signal.
  *
  * Since: 1.6