From d3adda2a14133f956acdc6bc7d3a6020f68cfb46 Mon Sep 17 00:00:00 2001
From: sanjeev <sanjeev@7cbeb6ba-43b4-40fd-8cce-4c39aea84d33>
Date: Mon, 20 Feb 2012 04:55:46 +0000
Subject: [PATCH] Add documentation to elm_video.h. API renaming to be done.

Signed-off-by: Sanjeev BA <iamsanjeev@gmail.com>

git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/elementary@68141 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33
---
 src/lib/elm_video.h | 83 +++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 74 insertions(+), 9 deletions(-)

diff --git a/src/lib/elm_video.h b/src/lib/elm_video.h
index 986b655..f33da08 100644
--- a/src/lib/elm_video.h
+++ b/src/lib/elm_video.h
@@ -5,16 +5,19 @@
  * @{
  *
  * Elementary comes with two object that help design application that need
- * to display video. The main one, Elm_Video, display a video by using Emotion.
- * It does embedded the video inside an Edje object, so you can do some
- * animation depending on the video state change. It does also implement a
- * resource management policy to remove this burden from the application writer.
+ * to display video. 
  *
- * The second one, Elm_Player is a video player that need to be linked with and Elm_Video.
+ * The first one, Elm_Video, display a video by using Emotion.
+ * It embeds the video inside an Edje object, so you can do some
+ * animation depending on the video state change. It also implements a
+ * resource management policy to remove this burden from the application.
+ *
+ * The second one, 
+ * Elm_Player is a video player that need to be linked with an Elm_Video. 
  * It take care of updating its content according to Emotion event and provide a
- * way to theme itself. It also does automatically raise the priority of the
- * linked Elm_Video so it will use the video decoder if available. It also does
- * activate the remember function on the linked Elm_Video object.
+ * way to theme itself. It also automatically raises the priority of the
+ * linked Elm_Video so it will use the video decoder, if available. It also
+ * activates the "remember" function on the linked Elm_Video object.
  *
  * Signals that you can add callback for are :
  *
@@ -206,12 +209,74 @@ EAPI double               elm_video_audio_level_get(const Evas_Object *video);
  */
 EAPI void                 elm_video_audio_level_set(Evas_Object *video, double volume);
 
-/* XXX: need docs for these */
+/**
+ * @brief Get the current position (in seconds) being played in the 
+ * Elm_Video object.
+ *
+ * @param video The video object.
+ * @return the time(in seconds) since the beginnig of the media file.
+ *
+ * @ingroup Video
+ */
 EAPI double               elm_video_play_position_get(const Evas_Object *video);
+
+/**
+ * @brief Set the current position (in seconds) to be played in the 
+ * Elm_Video object.
+ *
+ * @param video The video object.
+ * @param position the time(in seconds) since the beginnig of the media file.
+ *
+ * @ingroup Video
+ */
 EAPI void                 elm_video_play_position_set(Evas_Object *video, double position);
+/**
+ * @brief Get the total playing time (in seconds) of the Elm_Video object.
+ *
+ * @param video The video object.
+ * @return the total duration(in seconds) of the media file.
+ *
+ * @ingroup Video
+ */
 EAPI double               elm_video_play_length_get(const Evas_Object *video);
+
+/**
+ * @brief Set whether the object can remember the last played position.
+ *
+ * @param video The video object.
+ * @param remember the last played position of the Elm_Video object.
+ *
+ * @note This API only serves as indication. System support is required.
+ *
+ * @ingroup Video
+ */
 EAPI void                 elm_video_remember_position_set(Evas_Object *video, Eina_Bool remember);
+
+/**
+ * @brief Set whether the object can remember the last played position.
+ *
+ * @param video The video object.
+ * @return whether the object remembers the last played position (EINA_TRUE) 
+ * or not.
+ *
+ * @note This API only serves as indication. System support is required.
+ *
+ * @ingroup Video
+ */
 EAPI Eina_Bool            elm_video_remember_position_get(const Evas_Object *video);
+
+/**
+ * @brief Get the title (for ex. dvd title) from this emotion object.
+ *
+ * @param obj The Elm_Video object.
+ * @return A string containing the title.
+ *
+ * This function is only useful when playing a DVD.
+ *
+ * @note Don't change or free the string returned by this function.
+ *
+ * @ingroup Video
+ */
 EAPI const char          *elm_video_title_get(const Evas_Object *video);
 /**
  * @}
-- 
2.7.4