[Elementary.h] Add docs for pager

diff --git a/src/lib/Elementary.h.in b/src/lib/Elementary.h.in
index dc9a4d1..2179e30 100644 (file)
--- a/src/lib/Elementary.h.in
+++ b/src/lib/Elementary.h.in
@@ -19558,24 +19558,112 @@ extern "C" {
     * @}
     */
 
-   /* pager */
+   /**
+    * @defgroup Pager Pager
+    *
+    * @image html img/widget/pager/preview-00.png
+    * @image latex img/widget/pager/preview-00.eps
+    *
+    * @brief Widget that allows flipping between 1 or more “pages” of objects.
+    *
+    * The flipping between “pages” of objects is animated. All content in pager
+    * is kept in a stack, the last content to be added will be on the top of the
+    * stack(be visible).
+    *
+    * Objects can be pushed or popped from the stack or deleted as normal.
+    * Pushes and pops will animate (and a pop will delete the object once the
+    * animation is finished). Any object already in the pager can be promoted to
+    * the top(from its current stacking position) through the use of
+    * elm_pager_content_promote(). Objects are pushed to the top with
+    * elm_pager_content_push() and when the top item is no longer wanted, simply
+    * pop it with elm_pager_content_pop() and it will also be deleted. If an
+    * object is no longer needed and is not the top item, just delete it as
+    * normal. You can query which objects are the top and bottom with
+    * elm_pager_content_bottom_get() and elm_pager_content_top_get().
+    *
+    * Signals that you can add callbacks for are:
+    * "hide,finished" - when the previous page is hided
+    *
+    * This widget has the following styles available:
+    * @li default
+    * @li fade
+    * @li fade_translucide
+    * @li fade_invisible
+    * @note This styles affect only the flipping animations, the appearance when
+    * not animating is unaffected by styles.
+    *
+    * @ref tutorial_pager gives a good overview of the usage of the API.
+    * @{
+    */
+   /**
+    * Add a new pager to the parent
+    *
+    * @param parent The parent object
+    * @return The new object or NULL if it cannot be created
+    *
+    * @ingroup Pager
+    */
    EAPI Evas_Object *elm_pager_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Push an object to the top of the pager stack (and show it).
+    *
+    * @param obj The pager object
+    * @param content The object to push
+    *
+    * The object pushed becomes a child of the pager, it will be controlled and
+    * deleted when the pager is deleted.
+    *
+    * @note If the content is already in the stack use
+    * elm_pager_content_promote().
+    * @warning Using this function on @p content already in the stack results in
+    * undefined behavior.
+    */
    EAPI void         elm_pager_content_push(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Pop the object that is on top of the stack
+    *
+    * @param obj The pager object
+    *
+    * This pops the object that is on the top(visible) of the pager, makes it
+    * disappear, then deletes the object. The object that was underneath it on
+    * the stack will become visible.
+    */
    EAPI void         elm_pager_content_pop(Evas_Object *obj) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Moves an object already in the pager stack to the top of the stack.
+    *
+    * @param obj The pager object
+    * @param content The object to promote
+    *
+    * This will take the @p content and move it to the top of the stack as
+    * if it had been pushed there.
+    *
+    * @note If the content isn't already in the stack use
+    * elm_pager_content_push().
+    * @warning Using this function on @p content not already in the stack
+    * results in undefined behavior.
+    */
    EAPI void         elm_pager_content_promote(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Return the object at the bottom of the pager stack
+    *
+    * @param obj The pager object
+    * @return The bottom object or NULL if none
+    */
    EAPI Evas_Object *elm_pager_content_bottom_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+   /**
+    * @brief  Return the object at the top of the pager stack
+    *
+    * @param obj The pager object
+    * @return The top object or NULL if none
+    */
    EAPI Evas_Object *elm_pager_content_top_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
    EAPI void         elm_pager_to_content_pop(Evas_Object *obj, Evas_Object *content); EINA_ARG_NONNULL(1);
    EAPI void         elm_pager_animation_disabled_set(Evas_Object *obj, Eina_Bool disable); EINA_ARG_NONNULL(1);
 
-   /* available item styles:
-    * default
-    * fade
-    * fade_translucide
-    * fade_invisible
-    */
-   /* smart callbacks called:
-    * "hide,finished" - when the previous page is hided
+   /**
+    * @}
     */
 
    typedef struct _Elm_Slideshow_Item_Class Elm_Slideshow_Item_Class;