ecore_cocoa: start doxygen

1 files changed, 116 insertions, 29 deletions

diff --git a/src/lib/ecore_cocoa/Ecore_Cocoa.h b/src/lib/ecore_cocoa/Ecore_Cocoa.h
index caae2d0741..bd0e50246a 100644
--- a/src/lib/ecore_cocoa/Ecore_Cocoa.h
+++ b/src/lib/ecore_cocoa/Ecore_Cocoa.h
@@ -1,3 +1,10 @@
+/**
+ * @file Ecore_Cocoa.h
+ *
+ * @brief Ecore_Cocoa Wrapper Library to interact with the Cocoa
+ * envirnement (Mac OS X) from the E environment
+ *
+ */
 #ifndef __ECORE_COCOA_H__
 #define __ECORE_COCOA_H__
 
@@ -32,24 +39,53 @@
 extern "C" {
 #endif
 
+/**
+ * @typedef Ecore_Cocoa_Window
+ * Opaque handler to manipulate a Cocoa Window through Ecore
+ */
 typedef struct _Ecore_Cocoa_Window Ecore_Cocoa_Window;
+
+/**
+ * @typedef Ecore_Cocoa_Screen
+ * Opaque handler to manipulate a Cocoa Screen through Ecore
+ */
 typedef struct _Ecore_Cocoa_Screen Ecore_Cocoa_Screen;
 
+/**
+ * @typedef Ecore_Cocoa_Window_Id
+ * Opaque handler to reference the actual Cocoa window
+ */
+typedef void * Ecore_Cocoa_Window_Id;
+
+/**
+ * @typedef Ecore_Cocoa_Event_Video_Resize
+ * Type of event thrown when a window is resized
+ */
+typedef struct _Ecore_Cocoa_Event_Video_Resize Ecore_Cocoa_Event_Video_Resize;
+
+/** Event triggered when a window receives focus */
 EAPI extern int ECORE_COCOA_EVENT_GOT_FOCUS;
+
+/** Event triggered when a window loses focus */
 EAPI extern int ECORE_COCOA_EVENT_LOST_FOCUS;
+
+/** Event triggered when a window is resized */
 EAPI extern int ECORE_COCOA_EVENT_RESIZE;
+
 EAPI extern int ECORE_COCOA_EVENT_EXPOSE;
 EAPI extern int ECORE_COCOA_EVENT_WINDOW_DESTROY;
 EAPI extern int ECORE_COCOA_EVENT_DATA_SOURCE_SEND;
 EAPI extern int ECORE_COCOA_EVENT_SELECTION_DATA_READY;
 
-typedef void * Ecore_Cocoa_Window_Id;
-typedef struct _Ecore_Cocoa_Event_Video_Resize Ecore_Cocoa_Event_Video_Resize;
+/**
+ * @struct _Ecore_Cocoa_Event_Video_Resize
+ * Data available when a window is resized
+ */
 struct _Ecore_Cocoa_Event_Video_Resize
 {
-   int             w;
-   int             h;
-   Ecore_Cocoa_Window_Id wid;
+   int             w; /**< Current width of the window */
+   int             h; /**< Current height of the window */
+   Ecore_Cocoa_Window_Id wid; /**< Handler of the Cocoa window */
 };
 
 typedef struct _Ecore_Cocoa_Event_Window Ecore_Cocoa_Event_Window;
@@ -63,44 +99,109 @@ struct _Ecore_Cocoa_Screen
   int dummy;
 };
 
+/**
+ * @typedef Ecore_Cocoa_Cnp_Type
+ * Type used to interact with the Cocoa pasteboard.
+ * It hold types that can apply to a context.
+ */
 typedef enum
 {
-   ECORE_COCOA_CNP_TYPE_UNKNOWN = 0,
-   ECORE_COCOA_CNP_TYPE_STRING  = (1 << 0),
-   ECORE_COCOA_CNP_TYPE_MARKUP  = (1 << 1),
-   ECORE_COCOA_CNP_TYPE_IMAGE   = (1 << 2),
-   ECORE_COCOA_CNP_TYPE_HTML    = (1 << 3)
+   ECORE_COCOA_CNP_TYPE_UNKNOWN = 0, /**< Undefined type */
+   ECORE_COCOA_CNP_TYPE_STRING  = (1 << 0), /**< String type (pure text) */
+   ECORE_COCOA_CNP_TYPE_MARKUP  = (1 << 1), /**< Elementary markup */
+   ECORE_COCOA_CNP_TYPE_IMAGE   = (1 << 2), /**< Image (all formats) */
+   ECORE_COCOA_CNP_TYPE_HTML    = (1 << 3) /**< HTML */
 } Ecore_Cocoa_Cnp_Type;
 
-/* Core */
 
-EAPI int  ecore_cocoa_init(void);
-EAPI int  ecore_cocoa_shutdown(void);
+/*============================================================================*
+ *                                    Core                                    *
+ *============================================================================*/
+
+/**
+ * Inits the Ecore_Cocoa library
+ * @return How many times Ecore_Cocoa has been initted
+ */
+EAPI int ecore_cocoa_init(void);
+
+/**
+ * Shuts the Ecore_Cocoa library down
+ * @return How many times Ecore_Cocoa has been initted
+ */
+EAPI int ecore_cocoa_shutdown(void);
+
+// XXX Why is this public?
 EAPI Eina_Bool ecore_cocoa_feed_events(void *anEvent);
 
-/* Screen */
 
+/*============================================================================*
+ *                                   Screen                                   *
+ *============================================================================*/
+
+/**
+ * Retrieves the size of a Cocoa screen
+ * @param screen The screen which size must be retrieved
+ * @param [out] w The width of the screen
+ * @param [out] h The height of the screen
+ */
 EAPI void ecore_cocoa_screen_size_get(Ecore_Cocoa_Screen *screen, int *w, int *h);
 
-/* Window */
 
+/*============================================================================*
+ *                                   Window                                   *
+ *============================================================================*/
+
+/**
+ * Creates a Cocoa window
+ * @param x The origin (X) where the window must be created
+ * @param y The origin (Y) where the window must be created
+ * @param width The width of the window
+ * @param height The height of the window
+ * @return A handler on the window. NULL on failure
+ */
 EAPI Ecore_Cocoa_Window *ecore_cocoa_window_new(int x,
                                                 int y,
                                                 int width,
                                                 int height);
 
+/**
+ * Releases a Cocoa window
+ * @param window The window to be released
+ */
 EAPI void ecore_cocoa_window_free(Ecore_Cocoa_Window *window);
 
 EAPI void *ecore_cocoa_window_hwnd_get(Ecore_Cocoa_Window *window);
 
+/**
+ * Moves a Cocoa window to a given point
+ * @param window The window to be moved
+ * @param x The new origin of the window (X)
+ * @param y The new origin of the window (Y)
+ */
 EAPI void ecore_cocoa_window_move(Ecore_Cocoa_Window *window,
                                   int                 x,
                                   int                 y);
 
+/**
+ * Resizes a Cocoa window to a given size
+ * @param window The window to be moved
+ * @param width The new width of the window
+ * @param height The new height of the window
+ */
 EAPI void ecore_cocoa_window_resize(Ecore_Cocoa_Window *window,
                                     int                 width,
                                     int                 height);
 
+/**
+ * Moves and resizes a Cocoa window to a given point and size
+ * @param window The window to be moved
+ * @param x The new origin of the window (X)
+ * @param y The new origin of the window (Y)
+ * @param width The new width of the window
+ * @param height The new height of the window
+ * @see ecore_cocoa_window_resize()
+ * @see ecore_cocoa_window_move()
+ */
 EAPI void ecore_cocoa_window_move_resize(Ecore_Cocoa_Window *window,
                                          int                 x,
                                          int                 y,
@@ -178,25 +279,11 @@ EAPI int ecore_cocoa_titlebar_height_get(void);
 EAPI Ecore_Cocoa_Window_Id ecore_cocoa_window_get_window_id(const Ecore_Cocoa_Window *window);
 
 
-
-/**
- * @return false on error, true otherwise
- *
- * @ingroup Ecore_Cocoa_Cpn_Group
- */
 EAPI Eina_Bool ecore_cocoa_selection_clipboard_set(const void *data, int size, Ecore_Cocoa_Cnp_Type type);
 
-/**
- * @return false if type not found or on error, true otherwise
- *
- * @ingroup Ecore_Cocoa_Cnp_Group
- */
 EAPI void *ecore_cocoa_selection_clipboard_get(int *size, Ecore_Cocoa_Cnp_Type type,
                                                Ecore_Cocoa_Cnp_Type *retrieved_types);
 
-/**
- * @ingroup Ecore_Cocoa_Cnp_Group
- */
 EAPI void ecore_cocoa_selection_clipboard_clear(void);
 
 EAPI void ecore_cocoa_window_cursor_set(Ecore_Cocoa_Window *win, Ecore_Cocoa_Cursor c);