ecore_wayland: Improve API docs

Summary:
For calls that return pointers, specify that NULL is a
potential return value.  Add API documentation for some misc. routines
missing it.

Reviewers: zmike, cedric, devilhorns

Subscribers: cedric

Differential Revision: https://phab.enlightenment.org/D2180
This commit is contained in:
Bryce Harrington 2015-03-17 19:23:48 -04:00 committed by Mike Blumenkrantz
parent d54591720e
commit 931ac66be1
1 changed files with 114 additions and 10 deletions

View File

@ -231,8 +231,8 @@ struct _Ecore_Wl_Event_Interfaces_Bound
* @ingroup Ecore
* 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:
* Wayland protocol in implementing a 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
@ -327,7 +327,7 @@ EAPI void ecore_wl_sync(void);
/**
* Retrieves the Wayland Shm Interface used for the current Wayland connection.
*
* @return The current wayland shm interface
* @return The current wayland shm interface, or NULL on error
*
* @ingroup Ecore_Wl_Display_Group
* @since 1.2
@ -337,7 +337,7 @@ EAPI struct wl_shm *ecore_wl_shm_get(void);
/**
* Retrieves the Wayland Display Interface used for the current Wayland connection.
*
* @return The current wayland display interface
* @return The current wayland display interface, or NULL on error
*
* @ingroup Ecore_Wl_Display_Group
* @since 1.2
@ -350,7 +350,7 @@ EAPI struct wl_display *ecore_wl_display_get(void);
* This interface is used by clients to request the creation of surfaces and
* regions.
*
* @return The current wayland compositor interface
* @return The current wayland compositor interface, or NULL on error
* @since 1.8
*/
@ -364,6 +364,16 @@ EAPI struct wl_display *ecore_wl_display_get(void);
* @since 1.2
*/
EAPI void ecore_wl_screen_size_get(int *w, int *h);
/**
* Retrieves the position of the current screen.
*
* @param x where to return the horizontal position. May be NULL. Returns 0 on error.
* @param y where to return the vertical position. May be NULL. Returns 0 on error.
*
* @ingroup Ecore_Wl_Display_Group
* @since 1.2
*/
EAPI void ecore_wl_pointer_xy_get(int *x, int *y);
/**
@ -378,6 +388,14 @@ EAPI void ecore_wl_pointer_xy_get(int *x, int *y);
* @since 1.2
*/
EAPI int ecore_wl_dpi_get(void);
/**
* Dispatch Wayland events
*
* Dispatches any events queued on the default queue. Wayland will attempt
* to read from the display fd and queue things up according to the proxy
* assignment.
*/
EAPI void ecore_wl_display_iterate(void);
/*
@ -436,7 +454,7 @@ EAPI void ecore_wl_input_cursor_theme_name_set(Ecore_Wl_Input *input, const char
*
* There's no need to call dispatch manually, since this call will do it if necessary.
*
* @return The current wayland globals interface list
* @return The current wayland globals interface list, or NULL on error
*
* @ingroup Ecore_Wl_Display_Group
* @since 1.7.6
@ -446,7 +464,7 @@ EAPI Eina_Inlist *ecore_wl_globals_get(void);
/**
* Retrieves the Wayland Registry used for the current Wayland connection.
*
* @return The current wayland registry
* @return The current wayland registry, or NULL on error
*
* @ingroup Ecore_Wl_Display_Group
* @since 1.7.6
@ -471,7 +489,7 @@ EAPI struct wl_registry *ecore_wl_registry_get(void);
* @param h Height
* @param buffer_type The type of the buffer to be used to create a new Ecore_Wl_Window.
*
* @return The new window
* @return The new window, or NULL on failure
*
* @ingroup Ecore_Wl_Window_Group
* @since 1.2
@ -598,6 +616,7 @@ EAPI Ecore_Wl_Input *ecore_wl_window_keyboard_get(Ecore_Wl_Window *win);
* Returns a wl_surface with no association to any wl_shell_surface.
*
* @param win The window which will use this newly created surface.
* @return wl_surface or NULL on error
*
* @ingroup Ecore_Wl_Window_Group
* @since 1.8
@ -611,7 +630,7 @@ EAPI Eina_Bool ecore_wl_window_alpha_get(Ecore_Wl_Window *win);
* Returns the Ecore_Wl_Window from a wl_surface
*
* @param surface The surface for which to find the Ecore_Wl_Window from
* @return the Ecore_Wl_Window associated with this surface
* @return the Ecore_Wl_Window associated with this surface, or NULL if not found
*
* @ingroup Ecore_Wl_Window_Group
* @since 1.8
@ -710,24 +729,32 @@ EINA_DEPRECATED EAPI Eina_Bool ecore_wl_dnd_start_drag(Ecore_Wl_Dnd *dnd);
EINA_DEPRECATED EAPI Eina_Bool ecore_wl_dnd_selection_has_owner(Ecore_Wl_Dnd *dnd);
/**
* @return false on error, true otherwise
*
* @ingroup Ecore_Wl_Dnd_Group
* @since 1.8
*/
EAPI Eina_Bool ecore_wl_dnd_selection_set(Ecore_Wl_Input *input, const char **types_offered);
/**
* @return false if type not found or on error, true otherwise
*
* @ingroup Ecore_Wl_Dnd_Group
* @since 1.8
*/
EAPI Eina_Bool ecore_wl_dnd_selection_get(Ecore_Wl_Input *input, const char *type);
/**
* @return true if input has a selection source, false otherwise or on error
*
* @ingroup Ecore_Wl_Dnd_Group
* @since 1.8
*/
EAPI Eina_Bool ecore_wl_dnd_selection_owner_has(Ecore_Wl_Input *input);
/**
* @return false on error, true otherwise
*
* @ingroup Ecore_Wl_Dnd_Group
* @since 1.8
*/
@ -746,6 +773,8 @@ EAPI void ecore_wl_dnd_drag_start(Ecore_Wl_Input *input, Ecore_Wl_Window *win, E
EAPI void ecore_wl_dnd_drag_end(Ecore_Wl_Input *input);
/**
* @return false if type not found or on error, true otherwise
*
* @ingroup Ecore_Wl_Dnd_Group
* @since 1.8
*/
@ -769,6 +798,13 @@ EAPI struct wl_array *ecore_wl_dnd_drag_types_get(Ecore_Wl_Input *input);
*/
/* EAPI Ecore_Wl_Dnd_Source *ecore_wl_dnd_drag_source_create(Ecore_Wl_Dnd *dnd); */
/**
* Enable/disable server mode.
*
* With this enabled, the compositor acts as a Wayland server, iterating
* the display and dispatching events. With it disabled, the process is
* handled as a client.
*/
EAPI void ecore_wl_server_mode_set(Eina_Bool on);
/**
@ -794,6 +830,9 @@ EAPI void ecore_wl_server_mode_set(Eina_Bool on);
* The @param win must be visible, otherwise there will be no surface created
* for it yet.
*
* @return the allocated and initialized Ecore_Wl_Subsurf object, or
* NULL on failure
*
* @ingroup Ecore_Wl_Subsurf
* @since 1.8
*/
@ -802,13 +841,18 @@ EAPI Ecore_Wl_Subsurf *ecore_wl_subsurf_create(Ecore_Wl_Window *win);
/**
* Destroy the given subsurface, as well as the surface associated with it.
*
* @param ess the subsurface
*
* @ingroup Ecore_Wl_Subsurf
* @since 1.8
*/
EAPI void ecore_wl_subsurf_del(Ecore_Wl_Subsurf *ess);
/**
* Return the wl_surface associated with this subsurface.
* Get the wl_surface for this subsurface
*
* @param ess the subsurface
* @return the wl_surface associated with this subsurface, or NULL on failure
*
* @ingroup Ecore_Wl_Subsurf
* @since 1.8
@ -817,6 +861,12 @@ EAPI struct wl_surface *ecore_wl_subsurf_surface_get(Ecore_Wl_Subsurf *ess);
/**
* Set the position of this subsurface, relative to its parent surface.
* If ess is defined and the x, y coordinates differ from the currently
* tracked position, this also schedules a sub-surface position change.
*
* @param ess the subsurface
* @param x coordinate in the parent surface
* @param y coordinate in the parent surface
*
* @ingroup Ecore_Wl_Subsurf
* @since 1.8
@ -825,6 +875,11 @@ EAPI void ecore_wl_subsurf_position_set(Ecore_Wl_Subsurf *ess, int x, int y);
/**
* Get the position of this subsurface, relative to its parent surface.
* Coordinates will be returned in x and y if non-NULL.
*
* @param ess the subsurface
* @param x coordinate in the parent surface, or NULL to ignore
* @param y coordinate in the parent surface, or NULL to ignore
*
* @ingroup Ecore_Wl_Subsurf
* @since 1.8
@ -832,18 +887,57 @@ EAPI void ecore_wl_subsurf_position_set(Ecore_Wl_Subsurf *ess, int x, int y);
EAPI void ecore_wl_subsurf_position_get(Ecore_Wl_Subsurf *ess, int *x, int *y);
/**
* Place subsurface on layer above a reference surface
*
* Moves the @param ess subsurface to just above the reference @param
* surface, changing the z-order. The reference @param surface must
* be either a sibling or parent surface, else a protocol error will
* be generated.
*
* @param ess the subsurface
* @param surface the sibling reference surface
*
* @ingroup Ecore_Wl_Subsurf
* @since 1.8
*/
EAPI void ecore_wl_subsurf_place_above(Ecore_Wl_Subsurf *ess, struct wl_surface *surface);
/**
* Place subsurface on layer below a reference surface
*
* See ecore_wl_subsurf_place_above.
*
* @param ess the subsurface
* @param surface the sibling reference surface
*
* @ingroup Ecore_Wl_Subsurf
* @since 1.8
*/
EAPI void ecore_wl_subsurf_place_below(Ecore_Wl_Subsurf *ess, struct wl_surface *surface);
/**
* Enables or disables sub-surface synchronization
*
* When synchronization is enabled, surface commits on the subsurface
* will be cached and only applied when the parent surface's state is
* applied. This ensures atomic updates of the parent and all of its
* synchronized sub-surfaces.
*
* When synchronization is disabled, commits will apply to the pending
* state directly without caching, just like a normal wl_surface. If
* there are already cached events when this is set, those events are
* applied simultaneously with the desync event.
*
* Attempting to enable synchronization when the subsurface already
* thinks it's sync'd, or desync when it believes its desync'd, will
* be trivially ignored and will not generate a Wayland event.
*
* See Wayland's set_desync documentation for further details and
* exceptional cases.
*
* @param ess the subsurface
* @param val true to enable synchronization, false to desynchronize
*
* @ingroup Ecore_Wl_Subsurf
* @since 1.8
*/
@ -852,8 +946,18 @@ EAPI void ecore_wl_subsurf_sync_set(Ecore_Wl_Subsurf *ess, Eina_Bool val);
/**
* Set an opaque region for the given subsurface.
*
* This is an optimization hint to the compositor to allow it avoid
* redrawing content unnecessarily. Note that marking transparent
* content as opaque will cause repaint artifacts.
*
* Use a 0x0 region size to unset the opaque region.
*
* @param ess the subsurface
* @param x coordinate in the parent surface
* @param y coordinate in the parent surface
* @param w width to set as opaque
* @param h height to set as opaque
*
* @ingroup Ecore_Wl_Subsurf
* @since 1.8
*/