Ecore_Wayland: Add some doxy & @since.
authordevilhorns <devilhorns@7cbeb6ba-43b4-40fd-8cce-4c39aea84d33>
Tue, 28 Feb 2012 22:31:27 +0000 (22:31 +0000)
committerdevilhorns <devilhorns@7cbeb6ba-43b4-40fd-8cce-4c39aea84d33>
Tue, 28 Feb 2012 22:31:27 +0000 (22:31 +0000)
git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/ecore@68522 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33

src/lib/ecore_wayland/Ecore_Wayland.h
src/lib/ecore_wayland/ecore_wl.c
src/lib/ecore_wayland/ecore_wl_window.c

index ca048b2..7e94333 100644 (file)
@@ -251,7 +251,11 @@ struct _Ecore_Wl_Event_Dnd_Drop
  * Ecore_Wl provides a wrapper and convenience functions for using the 
  * Wayland window system. Function groups for this part of the library 
  * include the following:
+ * 
  * @li @ref Ecore_Wl_Init_Group
+ * @li @ref Ecore_Wl_Display_Group
+ * @li @ref Ecore_Wl_Flush_Group
+ * @li @ref Ecore_Wl_Window_Group
  */
 
 EAPI extern int ECORE_WL_EVENT_MOUSE_IN;
index 9b28ab4..308fdee 100644 (file)
@@ -217,6 +217,19 @@ ecore_wl_shutdown(void)
    return _ecore_wl_shutdown(EINA_TRUE);
 }
 
+/**
+ * @defgroup Ecore_Wl_Flush_Group Wayland Synchronization Functions
+ * 
+ * Functions that ensure that all commands which have been issued by the 
+ * Ecore Wayland library have been sent to the server.
+ */
+
+/**
+ * Sends all Wayland commands to the Wayland Display.
+ * 
+ * @ingroup Ecore_Wl_Flush_Group
+ * @since 1.2
+ */
 EAPI void 
 ecore_wl_flush(void)
 {
@@ -224,10 +237,16 @@ ecore_wl_flush(void)
 
    while (_ecore_wl_disp->mask & WL_DISPLAY_WRITABLE)
      wl_display_iterate(_ecore_wl_disp->wl.display, WL_DISPLAY_WRITABLE);
-
 //   wl_display_flush(_ecore_wl_disp->wl.display); // old flush code
 }
 
+/**
+ * Flushes the command buffer and waits until all requests have been 
+ * processed by the server.
+ * 
+ * @ingroup Ecore_Wl_Flush_Group
+ * @since 1.2
+ */
 EAPI void 
 ecore_wl_sync(void)
 {
@@ -238,18 +257,49 @@ ecore_wl_sync(void)
 //   wl_display_iterate(_ecore_wl_disp->wl.display, WL_DISPLAY_READABLE);
 }
 
+/**
+ * @defgroup Ecore_Wl_Display_Group Wayland Display Functions
+ * 
+ * Functions that set and retrieve various information about the Wayland Display.
+ */
+
+/**
+ * Retrieves the Wayland Shm Interface used for the current Wayland connection.
+ * 
+ * @return The current wayland shm interface
+ * 
+ * @ingroup Ecore_Wl_Display_Group
+ * @since 1.2
+ */
 EAPI struct wl_shm *
 ecore_wl_shm_get(void)
 {
    return _ecore_wl_disp->wl.shm;
 }
 
+/**
+ * Retrieves the Wayland Display Interface used for the current Wayland connection.
+ * 
+ * @return The current wayland display interface
+ * 
+ * @ingroup Ecore_Wl_Display_Group
+ * @since 1.2
+ */
 EAPI struct wl_display *
 ecore_wl_display_get(void)
 {
    return _ecore_wl_disp->wl.display;
 }
 
+/**
+ * Retrieves the size of the current screen.
+ * 
+ * @param w where to return the width. May be NULL. Returns 0 on error.
+ * @param h where to return the height. May be NULL. Returns 0 on error.
+ * 
+ * @ingroup Ecore_Wl_Display_Group
+ * @since 1.2
+ */
 EAPI void 
 ecore_wl_screen_size_get(int *w, int *h)
 {
index 4fd9ba3..e8a8bfb 100644 (file)
@@ -36,6 +36,27 @@ _ecore_wl_window_shutdown(void)
    _windows = NULL;
 }
 
+/**
+ * @defgroup Ecore_Wl_Window_Group Wayland Library Init and Shutdown Functions
+ * 
+ * Functions that can be used to create a Wayland window.
+ */
+
+/**
+ * Creates a new window
+ * 
+ * @param parent The parent window to use. If @p parent is @c 0, the root window 
+ *               of the default display is used.
+ * @param x      X Position
+ * @param y      Y position
+ * @param w      Width
+ * @param h      Height
+ * 
+ * @return The new window
+ * 
+ * @ingroup Ecore_Wl_Window_Group
+ * @since 1.2
+ */
 EAPI Ecore_Wl_Window *
 ecore_wl_window_new(Ecore_Wl_Window *parent, int x, int y, int w, int h, int buffer_type)
 {
@@ -68,6 +89,14 @@ ecore_wl_window_new(Ecore_Wl_Window *parent, int x, int y, int w, int h, int buf
    return win;
 }
 
+/**
+ * Deletes the given window
+ * 
+ * @param win The given window
+ * 
+ * @ingroup Ecore_Wl_Window_Group
+ * @since 1.2
+ */
 EAPI void 
 ecore_wl_window_free(Ecore_Wl_Window *win)
 {
@@ -96,6 +125,19 @@ ecore_wl_window_free(Ecore_Wl_Window *win)
 //   free(win);
 }
 
+/**
+ * Signals for Wayland to initiate a window move.
+ * 
+ * The position requested (@p x, @p y) is not honored by Wayland because 
+ * Wayland does not allow specific window placement to be set.
+ * 
+ * @param win The window to move.
+ * @param x   X Position
+ * @param y   Y Position
+ * 
+ * @ingroup Ecore_Wl_Window_Group
+ * @since 1.2
+ */
 EAPI void 
 ecore_wl_window_move(Ecore_Wl_Window *win, int x, int y)
 {
@@ -114,6 +156,20 @@ ecore_wl_window_move(Ecore_Wl_Window *win, int x, int y)
      }
 }
 
+/**
+ * Signals for Wayland to initiate a window resize.
+ * 
+ * The size requested (@p w, @p h) is not honored by Wayland because 
+ * Wayland does not allow specific window sizes to be set.
+ * 
+ * @param win      The window to resize.
+ * @param w        Width
+ * @param h        Height
+ * @param location The edge of the window from where the resize should start.
+ * 
+ * @ingroup Ecore_Wl_Window_Group
+ * @since 1.2
+ */
 EAPI void 
 ecore_wl_window_resize(Ecore_Wl_Window *win, int w, int h, int location)
 {
@@ -152,6 +208,16 @@ ecore_wl_window_buffer_attach(Ecore_Wl_Window *win, struct wl_buffer *buffer, in
      wl_surface_attach(win->surface, buffer, x, y);
 }
 
+/**
+ * Shows a window
+ * 
+ * Synonymous to "mapping" a window in Wayland System terminology.
+ * 
+ * @param win The window to show.
+ * 
+ * @ingroup Ecore_Wl_Window_Group
+ * @since 1.2
+ */
 EAPI void 
 ecore_wl_window_show(Ecore_Wl_Window *win)
 {
@@ -197,6 +263,16 @@ ecore_wl_window_show(Ecore_Wl_Window *win)
      }
 }
 
+/**
+ * Hides a window
+ * 
+ * Synonymous to "unmapping" a window in Wayland System terminology.
+ * 
+ * @param win The window to hide.
+ * 
+ * @ingroup Ecore_Wl_Window_Group
+ * @since 1.2
+ */
 EAPI void 
 ecore_wl_window_hide(Ecore_Wl_Window *win)
 {
@@ -209,6 +285,14 @@ ecore_wl_window_hide(Ecore_Wl_Window *win)
    win->surface = NULL;
 }
 
+/**
+ * Raises a window
+ * 
+ * @param win The window to raise.
+ * 
+ * @ingroup Ecore_Wl_Window_Group
+ * @since 1.2
+ */
 EAPI void 
 ecore_wl_window_raise(Ecore_Wl_Window *win)
 {