From 17f75c962798170b31f40341baac2205fbbc3ae7 Mon Sep 17 00:00:00 2001
From: ChunEon Park <hermet@hermet.pe.kr>
Date: Thu, 11 Sep 2014 12:17:56 +0900
Subject: [PATCH] evas: updated native surface documentation.

---
 src/lib/evas/Evas_Common.h | 33 ++++++++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/src/lib/evas/Evas_Common.h b/src/lib/evas/Evas_Common.h
index adafbdd570..3fc0da5857 100644
--- a/src/lib/evas/Evas_Common.h
+++ b/src/lib/evas/Evas_Common.h
@@ -419,17 +419,40 @@ struct _Evas_Pixel_Import_Source
 /* magic version number to know what the native surf struct looks like */
 #define EVAS_NATIVE_SURFACE_VERSION 2
 
+/**
+ * Native surface types that image object supports
+ *
+ * @see Evas_Native_Surface
+ * @see evas_object_image_native_surface_set()
+ */
 typedef enum _Evas_Native_Surface_Type
 {
-   EVAS_NATIVE_SURFACE_NONE,
-   EVAS_NATIVE_SURFACE_X11,
-   EVAS_NATIVE_SURFACE_OPENGL
+   EVAS_NATIVE_SURFACE_NONE, /**< No surface type */
+   EVAS_NATIVE_SURFACE_X11,  /**< X Window system based type. pixmap id or visual of the pixmap */
+   EVAS_NATIVE_SURFACE_OPENGL /**< OpenGL system based type. texture or framebuffer id*/
 } Evas_Native_Surface_Type;
 
+/**
+ * @brief A generic datatype for engine specific native surface information.
+ *
+ * Please fill up Evas_Native_Surface fields that regarded with current surface
+ * type. If you want to set the native surface type to
+ * EVAS_NATIVE_SURFACE_X11, you need to set union data with x11.visual or
+ * x11.pixmap. If you need to set the native surface as
+ * EVAS_NATIVE_SURFACE_OPENGL, on the other hand, you need to set union data
+ * with opengl.texture_id or opengl.framebuffer_id and so on. The version field
+ * should be set with EVAS_NATIVE_SURFACE_VERSION in order to check abi
+ * break in your application on the different efl library versions.
+ *
+ * @warning Native surface types totally depend on the system. Please
+ *          be aware that the types are supported on your system before using 
+ *          them.
+ * @see evas_object_image_native_surface_set()
+ */
 struct _Evas_Native_Surface
 {
-   int                      version;
-   Evas_Native_Surface_Type type;
+   int                      version; /**< Current Native Surface Version. Use EVAS_NATIVE_SURFACE_VERSION */
+   Evas_Native_Surface_Type type; /**< Surface type. @see Evas_Native_Surface_Type */
    union {
       struct
       {