[edje] Better doc for edje_object_part_swallow.

git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/edje@71630 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33

diff --git a/src/lib/Edje.h b/src/lib/Edje.h
index e330fde..4f72b3b 100644 (file)
--- a/src/lib/Edje.h
+++ b/src/lib/Edje.h
@@ -3122,18 +3122,40 @@ EAPI void *edje_object_text_markup_filter_callback_del(Evas_Object *obj, const c
 EAPI void *edje_object_text_markup_filter_callback_del_full(Evas_Object *obj, const char *part, Edje_Markup_Filter_Cb func, void *data);
 
 /**
- * @brief Swallows an object into the edje.
+ * @brief "Swallows" an object into one of the Edje object @c SWALLOW
+ * parts.
+ *
+ * @param obj A valid Edje object handle
+ * @param part The swallow part's name
+ * @param obj_swallow The object to occupy that part
+ *
+ * Swallowing an object into an Edje object is, for a given part of
+ * type @c SWALLOW in the EDC group which gave life to @a obj, to set
+ * an external object to be controlled by @a obj, being displayed
+ * exactly over that part's region inside the whole Edje object's
+ * viewport.
+ *
+ * From this point on, @a obj will have total control over @a
+ * obj_swallow's geometry and visibility. For instance, if @a obj is
+ * visible, as in @c evas_object_show(), the swallowed object will be
+ * visible too -- if the given @c SWALLOW part it's in is also
+ * visible. Other actions on @a obj will also reflect on the swallowed
+ * object as well (e.g. resizing, moving, raising/lowering, etc.).
+ *
+ * Finally, all internal changes to @a part, specifically, will
+ * reflect on the displaying of @a obj_swallow, for example state
+ * changes leading to different visibility states, geometries,
+ * positions, etc.
  *
- * @param obj A valid Evas_Object handle
- * @param part The part name
- * @param obj_swallow The object to swallow
+ * If an object has already been swallowed into this part, then it
+ * will first be unswallowed (as in edje_object_part_unswallow())
+ * before the new object is swallowed.
  *
- * Swallows the object into the edje part so that all geometry changes
- * for the part affect the swallowed object. (e.g. resize, move, show,
- * raise/lower, etc.).
+ * @note @a obj @b won't delete the swallowed object once it is
+ * deleted -- @a obj_swallow will get to an unparented state again.
  *
- * If an object has already been swallowed into this part, then it
- * will first be unswallowed before the new object is swallowed.
+ * For more details on EDC @c SWALLOW parts, see @ref edcref "syntax
+ * reference".
  */
 EAPI Eina_Bool        edje_object_part_swallow        (Evas_Object *obj, const char *part, Evas_Object *obj_swallow);