diff options
65 files changed, 399 insertions, 372 deletions
diff --git a/include/wlr/backend.h b/include/wlr/backend.h index d781f74d..86decad4 100644 --- a/include/wlr/backend.h +++ b/include/wlr/backend.h @@ -14,22 +14,25 @@ struct wlr_backend_impl; +/** + * A backend provides a set of input and output devices. + */ struct wlr_backend { const struct wlr_backend_impl *impl; struct { - /** Raised when destroyed, passed the wlr_backend reference */ + /** Raised when destroyed */ struct wl_signal destroy; - /** Raised when new inputs are added, passed the wlr_input_device */ + /** Raised when new inputs are added, passed the struct wlr_input_device */ struct wl_signal new_input; - /** Raised when new outputs are added, passed the wlr_output */ + /** Raised when new outputs are added, passed the struct wlr_output */ struct wl_signal new_output; } events; }; /** * Automatically initializes the most suitable backend given the environment. - * Will always return a multibackend. The backend is created but not started. + * Will always return a multi-backend. The backend is created but not started. * Returns NULL on failure. */ struct wlr_backend *wlr_backend_autocreate(struct wl_display *display); @@ -41,11 +44,11 @@ struct wlr_backend *wlr_backend_autocreate(struct wl_display *display); bool wlr_backend_start(struct wlr_backend *backend); /** * Destroy the backend and clean up all of its resources. Normally called - * automatically when the wl_display is destroyed. + * automatically when the struct wl_display is destroyed. */ void wlr_backend_destroy(struct wlr_backend *backend); /** - * Obtains the wlr_session reference from this backend if there is any. + * Obtains the struct wlr_session reference from this backend if there is any. * Might return NULL for backends that don't use a session. */ struct wlr_session *wlr_backend_get_session(struct wlr_backend *backend); diff --git a/include/wlr/backend/drm.h b/include/wlr/backend/drm.h index 800bc585..1617aa15 100644 --- a/include/wlr/backend/drm.h +++ b/include/wlr/backend/drm.h @@ -48,8 +48,9 @@ bool wlr_output_is_drm(struct wlr_output *output); uint32_t wlr_drm_connector_get_id(struct wlr_output *output); /** - * Tries to open non-master DRM FD. The compositor must not call `drmSetMaster` + * Tries to open non-master DRM FD. The compositor must not call drmSetMaster() * on the returned FD. + * * Returns a valid opened DRM FD, or -1 on error. */ int wlr_drm_backend_get_non_master_fd(struct wlr_backend *backend); @@ -71,7 +72,7 @@ struct wlr_drm_lease *wlr_drm_create_lease(struct wlr_output **outputs, void wlr_drm_lease_terminate(struct wlr_drm_lease *lease); /** - * Add mode to the list of available modes + * Add mode to the list of available modes. */ typedef struct _drmModeModeInfo drmModeModeInfo; struct wlr_output_mode *wlr_drm_connector_add_mode(struct wlr_output *output, diff --git a/include/wlr/backend/headless.h b/include/wlr/backend/headless.h index ff55746f..2516f3a6 100644 --- a/include/wlr/backend/headless.h +++ b/include/wlr/backend/headless.h @@ -18,9 +18,9 @@ */ struct wlr_backend *wlr_headless_backend_create(struct wl_display *display); /** - * Create a new headless output backed by an in-memory EGL framebuffer. You can - * read pixels from this framebuffer via wlr_renderer_read_pixels but it is - * otherwise not displayed. + * Create a new headless output. + * + * The buffers presented on the output won't be displayed to the user. */ struct wlr_output *wlr_headless_add_output(struct wlr_backend *backend, unsigned int width, unsigned int height); diff --git a/include/wlr/backend/interface.h b/include/wlr/backend/interface.h index f0cafb01..d5bb9bca 100644 --- a/include/wlr/backend/interface.h +++ b/include/wlr/backend/interface.h @@ -23,8 +23,8 @@ struct wlr_backend_impl { }; /** - * Initializes common state on a wlr_backend and sets the implementation to the - * provided wlr_backend_impl reference. + * Initializes common state on a struct wlr_backend and sets the implementation + * to the provided struct wlr_backend_impl reference. */ void wlr_backend_init(struct wlr_backend *backend, const struct wlr_backend_impl *impl); diff --git a/include/wlr/backend/libinput.h b/include/wlr/backend/libinput.h index 94197b7a..83d281f9 100644 --- a/include/wlr/backend/libinput.h +++ b/include/wlr/backend/libinput.h @@ -18,7 +18,9 @@ struct wlr_input_device; struct wlr_backend *wlr_libinput_backend_create(struct wl_display *display, struct wlr_session *session); -/** Gets the underlying libinput_device handle for the given wlr_input_device */ +/** + * Gets the underlying struct libinput_device handle for the given input device. + */ struct libinput_device *wlr_libinput_get_device_handle( struct wlr_input_device *dev); diff --git a/include/wlr/backend/session.h b/include/wlr/backend/session.h index c8461ff7..e5deda57 100644 --- a/include/wlr/backend/session.h +++ b/include/wlr/backend/session.h @@ -79,36 +79,33 @@ struct wlr_device_change_event { * This should not be called if another program is already in control * of the terminal (Xorg, another Wayland compositor, etc.). * - * If libseat support is not enabled, or if a standalone backend is to be used, - * then you must have CAP_SYS_ADMIN or be root. It is safe to drop privileges - * after this is called. - * * Returns NULL on error. */ struct wlr_session *wlr_session_create(struct wl_display *disp); /* * Closes a previously opened session and restores the virtual terminal. - * You should call wlr_session_close_file on each files you opened - * with wlr_session_open_file before you call this. + * You should call wlr_session_close_file() on each files you opened + * with wlr_session_open_file() before you call this. */ void wlr_session_destroy(struct wlr_session *session); /* * Opens the file at path. - * This can only be used to open DRM or evdev (input) devices. + * + * This can only be used to open DRM or evdev (input) devices. Files opened via + * this function must be closed by calling wlr_session_close_file(). * * When the session becomes inactive: + * * - DRM files lose their DRM master status * - evdev files become invalid and should be closed - * - * Returns -errno on error. */ struct wlr_device *wlr_session_open_file(struct wlr_session *session, const char *path); /* - * Closes a file previously opened with wlr_session_open_file. + * Closes a file previously opened with wlr_session_open_file(). */ void wlr_session_close_file(struct wlr_session *session, struct wlr_device *device); diff --git a/include/wlr/backend/wayland.h b/include/wlr/backend/wayland.h index 0aed3aa1..a5b5e7a3 100644 --- a/include/wlr/backend/wayland.h +++ b/include/wlr/backend/wayland.h @@ -9,18 +9,18 @@ struct wlr_input_device; /** - * Creates a new wlr_wl_backend. This backend will be created with no outputs; - * you must use wlr_wl_output_create to add them. + * Creates a new Wayland backend. This backend will be created with no outputs; + * you must use wlr_wl_output_create() to add them. * * The `remote` argument is the name of the host compositor wayland socket. Set * to NULL for the default behaviour (WAYLAND_DISPLAY env variable or wayland-0 - * default) + * default). */ struct wlr_backend *wlr_wl_backend_create(struct wl_display *display, const char *remote); /** - * Returns the remote wl_display used by the Wayland backend. + * Returns the remote struct wl_display used by the Wayland backend. */ struct wl_display *wlr_wl_backend_get_remote_display(struct wlr_backend *backend); @@ -28,37 +28,37 @@ struct wl_display *wlr_wl_backend_get_remote_display(struct wlr_backend *backend * Adds a new output to this backend. You may remove outputs by destroying them. * Note that if called before initializing the backend, this will return NULL * and your outputs will be created during initialization (and given to you via - * the output_add signal). + * the new_output signal). */ struct wlr_output *wlr_wl_output_create(struct wlr_backend *backend); /** - * True if the given backend is a wlr_wl_backend. + * Check whether the provided backend is a Wayland backend. */ bool wlr_backend_is_wl(struct wlr_backend *backend); /** - * True if the given input device is a wlr_wl_input_device. + * Check whether the provided input device is a Wayland input device. */ bool wlr_input_device_is_wl(struct wlr_input_device *device); /** - * True if the given output is a wlr_wl_output. + * Check whether the provided output device is a Wayland output device. */ bool wlr_output_is_wl(struct wlr_output *output); /** - * Sets the title of a wlr_output which is a Wayland window. + * Sets the title of a struct wlr_output which is a Wayland toplevel. */ void wlr_wl_output_set_title(struct wlr_output *output, const char *title); /** - * Returns the remote wl_surface used by the Wayland output. + * Returns the remote struct wl_surface used by the Wayland output. */ struct wl_surface *wlr_wl_output_get_surface(struct wlr_output *output); /** - * Returns the remote wl_seat for a Wayland input device. + * Returns the remote struct wl_seat for a Wayland input device. */ struct wl_seat *wlr_wl_input_device_get_seat(struct wlr_input_device *dev); diff --git a/include/wlr/backend/x11.h b/include/wlr/backend/x11.h index c6aaaf80..54d91c75 100644 --- a/include/wlr/backend/x11.h +++ b/include/wlr/backend/x11.h @@ -11,11 +11,11 @@ struct wlr_input_device; /** - * Creates a new wlr_x11_backend. This backend will be created with no outputs; - * you must use wlr_x11_output_create to add them. + * Creates a new X11 backend. This backend will be created with no outputs; + * you must use wlr_x11_output_create() to add them. * * The `x11_display` argument is the name of the X Display socket. Set - * to NULL for the default behaviour of XOpenDisplay. + * to NULL for the default behaviour of XOpenDisplay(). */ struct wlr_backend *wlr_x11_backend_create(struct wl_display *display, const char *x11_display); @@ -24,27 +24,27 @@ struct wlr_backend *wlr_x11_backend_create(struct wl_display *display, * Adds a new output to this backend. You may remove outputs by destroying them. * Note that if called before initializing the backend, this will return NULL * and your outputs will be created during initialization (and given to you via - * the output_add signal). + * the new_output signal). */ struct wlr_output *wlr_x11_output_create(struct wlr_backend *backend); /** - * True if the given backend is a wlr_x11_backend. + * Check whether this backend is an X11 backend. */ bool wlr_backend_is_x11(struct wlr_backend *backend); /** - * True if the given input device is a wlr_x11_input_device. + * Check whether this input device is an X11 input device. */ bool wlr_input_device_is_x11(struct wlr_input_device *device); /** - * True if the given output is a wlr_x11_output. + * Check whether this output device is an X11 output device. */ bool wlr_output_is_x11(struct wlr_output *output); /** - * Sets the title of a wlr_output which is an X11 window. + * Sets the title of a struct wlr_output which is an X11 window. */ void wlr_x11_output_set_title(struct wlr_output *output, const char *title); diff --git a/include/wlr/interfaces/wlr_buffer.h b/include/wlr/interfaces/wlr_buffer.h index 05ccc1e7..820300f6 100644 --- a/include/wlr/interfaces/wlr_buffer.h +++ b/include/wlr/interfaces/wlr_buffer.h @@ -31,16 +31,16 @@ struct wlr_buffer_resource_interface { /** * Initialize a buffer. This function should be called by producers. The * initialized buffer is referenced: once the producer is done with the buffer - * they should call wlr_buffer_drop. + * they should call wlr_buffer_drop(). */ void wlr_buffer_init(struct wlr_buffer *buffer, const struct wlr_buffer_impl *impl, int width, int height); /** - * Allows the registration of a wl_resource implementation. + * Allows the registration of a struct wl_resource implementation. * - * The matching function will be called for the wl_resource when creating a - * wlr_buffer from a wl_resource. + * The matching function will be called for the struct wl_resource when creating + * a struct wlr_buffer from a struct wl_resource. */ void wlr_buffer_register_resource_interface( const struct wlr_buffer_resource_interface *iface); diff --git a/include/wlr/interfaces/wlr_keyboard.h b/include/wlr/interfaces/wlr_keyboard.h index 06b07989..2ec7c8cf 100644 --- a/include/wlr/interfaces/wlr_keyboard.h +++ b/include/wlr/interfaces/wlr_keyboard.h @@ -21,7 +21,7 @@ void wlr_keyboard_init(struct wlr_keyboard *keyboard, const struct wlr_keyboard_impl *impl, const char *name); /** - * Cleans up all of the resources owned by wlr_keyboard. + * Cleans up all of the resources owned by the struct wlr_keyboard. */ void wlr_keyboard_finish(struct wlr_keyboard *keyboard); diff --git a/include/wlr/interfaces/wlr_output.h b/include/wlr/interfaces/wlr_output.h index c02a588f..4de02c0b 100644 --- a/include/wlr/interfaces/wlr_output.h +++ b/include/wlr/interfaces/wlr_output.h @@ -26,7 +26,7 @@ WLR_OUTPUT_STATE_SUBPIXEL) /** - * A backend implementation of wlr_output. + * A backend implementation of struct wlr_output. * * The commit function is mandatory. Other functions are optional. */ @@ -39,7 +39,7 @@ struct wlr_output_impl { * The hotspot indicates the offset that needs to be applied to the * top-left corner of the image to match the cursor position. In other * words, the image should be displayed at (x - hotspot_x, y - hotspot_y). - * The hotspot is given in the texture's coordinate space. + * The hotspot is given in the buffer's coordinate space. */ bool (*set_cursor)(struct wlr_output *output, struct wlr_buffer *buffer, int hotspot_x, int hotspot_y); diff --git a/include/wlr/interfaces/wlr_tablet_pad.h b/include/wlr/interfaces/wlr_tablet_pad.h index e052dd83..f4a422f2 100644 --- a/include/wlr/interfaces/wlr_tablet_pad.h +++ b/include/wlr/interfaces/wlr_tablet_pad.h @@ -19,9 +19,11 @@ void wlr_tablet_pad_init(struct wlr_tablet_pad *pad, const struct wlr_tablet_pad_impl *impl, const char *name); /** - * Cleans up the resources owned by a wlr_tablet_pad. - * This function will not clean the memory allocated by wlr_tablet_pad_group, - * it's the responsibility of the caller to clean it. + * Cleans up the resources owned by a struct wlr_tablet_pad. + * + * This function will not clean the memory allocated by + * struct wlr_tablet_pad_group, it's the responsibility of the caller to clean + * it. */ void wlr_tablet_pad_finish(struct wlr_tablet_pad *pad); diff --git a/include/wlr/render/allocator.h b/include/wlr/render/allocator.h index 3150e36c..f5bb7522 100644 --- a/include/wlr/render/allocator.h +++ b/include/wlr/render/allocator.h @@ -37,7 +37,7 @@ struct wlr_allocator { }; /** - * Creates the adequate wlr_allocator given a backend and a renderer + * Creates the adequate struct wlr_allocator given a backend and a renderer. */ struct wlr_allocator *wlr_allocator_autocreate(struct wlr_backend *backend, struct wlr_renderer *renderer); @@ -50,7 +50,7 @@ void wlr_allocator_destroy(struct wlr_allocator *alloc); * Allocate a new buffer. * * When the caller is done with it, they must unreference it by calling - * wlr_buffer_drop. + * wlr_buffer_drop(). * * The `format` passed in indicates the format to use and the list of * acceptable modifiers. The order in which modifiers are listed is not diff --git a/include/wlr/render/drm_format_set.h b/include/wlr/render/drm_format_set.h index 9f4a86ea..6dbdc749 100644 --- a/include/wlr/render/drm_format_set.h +++ b/include/wlr/render/drm_format_set.h @@ -51,7 +51,7 @@ struct wlr_drm_format_set { void wlr_drm_format_set_finish(struct wlr_drm_format_set *set); /** - * Return a pointer to a member of this `wlr_drm_format_set` of format + * Return a pointer to a member of this struct wlr_drm_format_set of format * `format`, or NULL if none exists. */ const struct wlr_drm_format *wlr_drm_format_set_get( diff --git a/include/wlr/render/egl.h b/include/wlr/render/egl.h index 0d84958b..e4416e0b 100644 --- a/include/wlr/render/egl.h +++ b/include/wlr/render/egl.h @@ -77,7 +77,7 @@ struct wlr_egl *wlr_egl_create_with_context(EGLDisplay display, * Make the EGL context current. * * Callers are expected to clear the current context when they are done by - * calling wlr_egl_unset_current. + * calling wlr_egl_unset_current(). */ bool wlr_egl_make_current(struct wlr_egl *egl); diff --git a/include/wlr/render/wlr_renderer.h b/include/wlr/render/wlr_renderer.h index d8b04dc7..50ba6b21 100644 --- a/include/wlr/render/wlr_renderer.h +++ b/include/wlr/render/wlr_renderer.h @@ -77,13 +77,13 @@ void wlr_render_quad_with_matrix(struct wlr_renderer *r, const float color[static 4], const float matrix[static 9]); /** * Get the shared-memory formats supporting import usage. Buffers allocated - * with a format from this list may be imported via wlr_texture_from_pixels. + * with a format from this list may be imported via wlr_texture_from_pixels(). */ const uint32_t *wlr_renderer_get_shm_texture_formats( struct wlr_renderer *r, size_t *len); /** * Get the DMA-BUF formats supporting sampling usage. Buffers allocated with - * a format from this list may be imported via wlr_texture_from_dmabuf. + * a format from this list may be imported via wlr_texture_from_dmabuf(). */ const struct wlr_drm_format_set *wlr_renderer_get_dmabuf_texture_formats( struct wlr_renderer *renderer); @@ -92,7 +92,7 @@ const struct wlr_drm_format_set *wlr_renderer_get_dmabuf_texture_formats( * bytes. * * If `flags` is not NULl, the caller indicates that it accepts frame flags - * defined in `enum wlr_renderer_read_pixels_flags`. + * defined in enum wlr_renderer_read_pixels_flags. */ bool wlr_renderer_read_pixels(struct wlr_renderer *r, uint32_t fmt, uint32_t *flags, uint32_t stride, uint32_t width, uint32_t height, @@ -107,7 +107,7 @@ bool wlr_renderer_init_wl_display(struct wlr_renderer *r, struct wl_display *wl_display); /** - * Initializes wl_shm on the provided wl_display. + * Initializes wl_shm on the provided struct wl_display. */ bool wlr_renderer_init_wl_shm(struct wlr_renderer *r, struct wl_display *wl_display); @@ -120,7 +120,9 @@ bool wlr_renderer_init_wl_shm(struct wlr_renderer *r, int wlr_renderer_get_drm_fd(struct wlr_renderer *r); /** - * Destroys this wlr_renderer. Textures must be destroyed separately. + * Destroys the renderer. + * + * Textures must be destroyed separately. */ void wlr_renderer_destroy(struct wlr_renderer *renderer); diff --git a/include/wlr/render/wlr_texture.h b/include/wlr/render/wlr_texture.h index 90bb5de5..93fc221c 100644 --- a/include/wlr/render/wlr_texture.h +++ b/include/wlr/render/wlr_texture.h @@ -51,7 +51,7 @@ bool wlr_texture_write_pixels(struct wlr_texture *texture, const void *data); /** - * Destroys this wlr_texture. + * Destroys the texture. */ void wlr_texture_destroy(struct wlr_texture *texture); diff --git a/include/wlr/types/wlr_buffer.h b/include/wlr/types/wlr_buffer.h index 604dc17a..17b93e5c 100644 --- a/include/wlr/types/wlr_buffer.h +++ b/include/wlr/types/wlr_buffer.h @@ -27,8 +27,8 @@ struct wlr_shm_attributes { /** * Buffer capabilities. * - * These bits indicate the features supported by a wlr_buffer. There is one bit - * per function in wlr_buffer_impl. + * These bits indicate the features supported by a struct wlr_buffer. There is + * one bit per function in struct wlr_buffer_impl. */ enum wlr_buffer_cap { WLR_BUFFER_CAP_DATA_PTR = 1 << 0, @@ -69,7 +69,7 @@ void wlr_buffer_drop(struct wlr_buffer *buffer); /** * Lock the buffer. This function should be called by consumers to make * sure the buffer can be safely read from. Once the consumer is done with the - * buffer, they should call wlr_buffer_unlock. + * buffer, they should call wlr_buffer_unlock(). */ struct wlr_buffer *wlr_buffer_lock(struct wlr_buffer *buffer); /** @@ -82,7 +82,7 @@ void wlr_buffer_unlock(struct wlr_buffer *buffer); * returns false. * * The returned DMA-BUF attributes are valid for the lifetime of the - * wlr_buffer. The caller isn't responsible for cleaning up the DMA-BUF + * struct wlr_buffer. The caller isn't responsible for cleaning up the DMA-BUF * attributes. */ bool wlr_buffer_get_dmabuf(struct wlr_buffer *buffer, @@ -92,16 +92,16 @@ bool wlr_buffer_get_dmabuf(struct wlr_buffer *buffer, * memory, returns false. * * The returned shared memory attributes are valid for the lifetime of the - * wlr_buffer. The caller isn't responsible for cleaning up the shared memory - * attributes. + * struct wlr_buffer. The caller isn't responsible for cleaning up the shared + * memory attributes. */ bool wlr_buffer_get_shm(struct wlr_buffer *buffer, struct wlr_shm_attributes *attribs); /** - * Transforms a wl_resource into a wlr_buffer and locks it. Once the caller is - * done with the buffer, they must call wlr_buffer_unlock. + * Transforms a struct wl_resource into a struct wlr_buffer and locks it. Once + * the caller is done with the buffer, they must call wlr_buffer_unlock(). * - * The provided wl_resource must be a wl_buffer. + * The provided struct wl_resource must be a wl_buffer. */ struct wlr_buffer *wlr_buffer_from_resource(struct wl_resource *resource); @@ -126,7 +126,7 @@ enum wlr_buffer_data_ptr_access_flag { * * The returned pointer should be pointing to a valid memory region for the * operations specified in the flags. The returned pointer is only valid up to - * the next buffer_end_data_ptr_access call. + * the next wlr_buffer_end_data_ptr_access() call. */ bool wlr_buffer_begin_data_ptr_access(struct wlr_buffer *buffer, uint32_t flags, void **data, uint32_t *format, size_t *stride); @@ -157,8 +157,8 @@ struct wlr_client_buffer { }; /** - * Creates a wlr_client_buffer from a given wlr_buffer by creating a texture - * from it, and copying its wl_resource. + * Creates a struct wlr_client_buffer from a given struct wlr_buffer by creating + * a texture from it, and copying its struct wl_resource. */ struct wlr_client_buffer *wlr_client_buffer_create(struct wlr_buffer *buffer, struct wlr_renderer *renderer); diff --git a/include/wlr/types/wlr_compositor.h b/include/wlr/types/wlr_compositor.h index 071610b8..bff6bc83 100644 --- a/include/wlr/types/wlr_compositor.h +++ b/include/wlr/types/wlr_compositor.h @@ -147,7 +147,7 @@ struct wlr_surface { struct wl_signal destroy; } events; - struct wl_list current_outputs; // wlr_surface_output::link + struct wl_list current_outputs; // wlr_surface_output.link struct wlr_addon_set addons; void *data; @@ -243,9 +243,10 @@ void wlr_surface_send_frame_done(struct wlr_surface *surface, void wlr_surface_get_extends(struct wlr_surface *surface, struct wlr_box *box); /** - * Get the wlr_surface corresponding to a wl_surface resource. This asserts - * that the resource is a valid wl_surface resource created by wlroots and - * will never return NULL. + * Get the struct wlr_surface corresponding to a wl_surface resource. + * + * This asserts that the resource is a valid wl_surface resource created by + * wlroots and will never return NULL. */ struct wlr_surface *wlr_surface_from_resource(struct wl_resource *resource); @@ -281,7 +282,7 @@ void wlr_surface_get_buffer_source_box(struct wlr_surface *surface, * Acquire a lock for the pending surface state. * * The state won't be committed before the caller releases the lock. Instead, - * the state becomes cached. The caller needs to use wlr_surface_unlock_cached + * the state becomes cached. The caller needs to use wlr_surface_unlock_cached() * to release the lock. * * Returns a surface commit sequence number for the cached state. diff --git a/include/wlr/types/wlr_cursor.h b/include/wlr/types/wlr_cursor.h index 95a3e37f..06ae2f1f 100644 --- a/include/wlr/types/wlr_cursor.h +++ b/include/wlr/types/wlr_cursor.h @@ -18,12 +18,12 @@ struct wlr_input_device; /** * wlr_cursor implements the behavior of the "cursor", that is, the image on the * screen typically moved about with a mouse or so. It provides tracking for - * this in global coordinates, and integrates with wlr_output, - * wlr_output_layout, and wlr_input_device. You can use it to abstract multiple - * input devices over a single cursor, constrain cursor movement to the usable - * area of a wlr_output_layout and communicate position updates to the hardware - * cursor, constrain specific input devices to specific outputs or regions of - * the screen, and so on. + * this in global coordinates, and integrates with struct wlr_output, + * struct wlr_output_layout, and struct wlr_input_device. You can use it to + * abstract multiple input devices over a single cursor, constrain cursor + * movement to the usable area of a struct wlr_output_layout and communicate + * position updates to the hardware cursor, constrain specific input devices to + * specific outputs or regions of the screen, and so on. */ struct wlr_box; @@ -37,15 +37,15 @@ struct wlr_cursor { * The interpretation of these signals is the responsibility of the * compositor, but some helpers are provided for your benefit. If you * receive a relative motion event, for example, you may want to call - * wlr_cursor_move. If you receive an absolute event, call - * wlr_cursor_warp_absolute. If you pass an input device into these + * wlr_cursor_move(). If you receive an absolute event, call + * wlr_cursor_warp_absolute(). If you pass an input device into these * functions, it will apply the region/output constraints associated with * that device to the resulting cursor motion. If an output layout is * attached, these functions will constrain the resulting cursor motion to * within the usable space of the output layout. * - * Re-broadcasting these signals to, for example, a wlr_seat, is also your - * responsibility. + * Re-broadcasting these signals to, for example, a struct wlr_seat, is also + * your responsibility. */ struct { struct wl_signal motion; @@ -191,13 +191,14 @@ void wlr_cursor_map_input_to_output(struct wlr_cursor *cur, struct wlr_input_device *dev, struct wlr_output *output); /** - * Maps this cursor to an arbitrary region on the associated wlr_output_layout. + * Maps this cursor to an arbitrary region on the associated + * struct wlr_output_layout. */ void wlr_cursor_map_to_region(struct wlr_cursor *cur, const struct wlr_box *box); /** * Maps inputs from this input device to an arbitrary region on the associated - * wlr_output_layout. + * struct wlr_output_layout. */ void wlr_cursor_map_input_to_region(struct wlr_cursor *cur, struct wlr_input_device *dev, const struct wlr_box *box); diff --git a/include/wlr/types/wlr_data_control_v1.h b/include/wlr/types/wlr_data_control_v1.h index c7e0adf0..4435f14a 100644 --- a/include/wlr/types/wlr_data_control_v1.h +++ b/include/wlr/types/wlr_data_control_v1.h @@ -14,7 +14,7 @@ struct wlr_data_control_manager_v1 { struct wl_global *global; - struct wl_list devices; // wlr_data_control_device_v1::link + struct wl_list devices; // wlr_data_control_device_v1.link struct { struct wl_signal destroy; @@ -27,7 +27,7 @@ struct wlr_data_control_manager_v1 { struct wlr_data_control_device_v1 { struct wl_resource *resource; struct wlr_data_control_manager_v1 *manager; - struct wl_list link; // wlr_data_control_manager_v1::devices + struct wl_list link; // wlr_data_control_manager_v1.devices struct wlr_seat *seat; struct wl_resource *selection_offer_resource; // current selection offer diff --git a/include/wlr/types/wlr_data_device.h b/include/wlr/types/wlr_data_device.h index 87c578ae..9f2481e6 100644 --- a/include/wlr/types/wlr_data_device.h +++ b/include/wlr/types/wlr_data_device.h @@ -43,7 +43,7 @@ struct wlr_data_offer { struct wl_resource *resource; struct wlr_data_source *source; enum wlr_data_offer_type type; - struct wl_list link; // wlr_seat::{selection_offers,drag_offers} + struct wl_list link; // wlr_seat.{selection_offers,drag_offers} uint32_t actions; enum wl_data_device_manager_dnd_action preferred_action; @@ -54,7 +54,7 @@ struct wlr_data_offer { /** * A data source implementation. Only the `send` function is mandatory. Refer to - * the matching wl_data_source_* functions documentation to know what they do. + * the matching `wlr_data_source_*` functions documentation to know what they do. */ struct wlr_data_source_impl { void (*send)(struct wlr_data_source *source, const char *mime_type, @@ -131,8 +131,8 @@ struct wlr_drag { struct { struct wl_signal focus; - struct wl_signal motion; // wlr_drag_motion_event - struct wl_signal drop; // wlr_drag_drop_event + struct wl_signal motion; // struct wlr_drag_motion_event + struct wl_signal drop; // struct wlr_drag_drop_event struct wl_signal destroy; } events; @@ -155,7 +155,7 @@ struct wlr_drag_drop_event { }; /** - * Create a wl data device manager global for this display. + * Create a wl_data_device_manager global for this display. */ struct wlr_data_device_manager *wlr_data_device_manager_create( struct wl_display *display); @@ -181,7 +181,7 @@ void wlr_seat_set_selection(struct wlr_seat *seat, /** * Creates a new drag. To request to start the drag, call - * `wlr_seat_request_start_drag`. + * wlr_seat_request_start_drag(). */ struct wlr_drag *wlr_drag_create(struct wlr_seat_client *seat_client, struct wlr_data_source *source, struct wlr_surface *icon_surface); @@ -258,7 +258,7 @@ void wlr_data_source_dnd_finish(struct wlr_data_source *source); * Notifies the data source that a target accepts the drag with the specified * action. * - * This shouldn't be called after `wlr_data_source_dnd_drop` unless the + * This shouldn't be called after wlr_data_source_dnd_drop() unless the * drag-and-drop operation ended in an "ask" action. */ void wlr_data_source_dnd_action(struct wlr_data_source *source, diff --git a/include/wlr/types/wlr_drm_lease_v1.h b/include/wlr/types/wlr_drm_lease_v1.h index 5a7827ea..314eb8cc 100644 --- a/include/wlr/types/wlr_drm_lease_v1.h +++ b/include/wlr/types/wlr_drm_lease_v1.h @@ -15,7 +15,7 @@ struct wlr_backend; struct wlr_output; struct wlr_drm_lease_v1_manager { - struct wl_list devices; // wlr_drm_lease_device_v1::link; + struct wl_list devices; // wlr_drm_lease_device_v1.link struct wl_display *display; struct wl_listener display_destroy; @@ -23,9 +23,9 @@ struct wlr_drm_lease_v1_manager { struct { /** * Upon receiving this signal, call - * wlr_drm_lease_device_v1_grant_lease_request to grant a lease of the + * wlr_drm_lease_device_v1_grant_lease_request() to grant a lease of the * requested DRM resources, or - * wlr_drm_lease_device_v1_reject_lease_request to reject the request. + * wlr_drm_lease_device_v1_reject_lease_request() to reject the request. */ struct wl_signal request; } events; @@ -38,10 +38,10 @@ struct wlr_drm_lease_device_v1 { struct wlr_drm_lease_v1_manager *manager; struct wlr_backend *backend; - struct wl_list connectors; // wlr_drm_lease_connector_v1::link - struct wl_list leases; // wlr_drm_lease_v1::link - struct wl_list requests; // wlr_drm_lease_request_v1::link - struct wl_list link; // wlr_drm_lease_v1_manager::devices + struct wl_list connectors; // wlr_drm_lease_connector_v1.link + struct wl_list leases; // wlr_drm_lease_v1.link + struct wl_list requests; // wlr_drm_lease_request_v1.link + struct wl_list link; // wlr_drm_lease_v1_manager.devices struct wl_listener backend_destroy; @@ -51,7 +51,7 @@ struct wlr_drm_lease_device_v1 { struct wlr_drm_lease_v1; struct wlr_drm_lease_connector_v1 { - struct wl_list resources; // wl_resource_get_link + struct wl_list resources; // wl_resource_get_link() struct wlr_output *output; struct wlr_drm_lease_device_v1 *device; @@ -60,7 +60,7 @@ struct wlr_drm_lease_connector_v1 { struct wl_listener destroy; - struct wl_list link; // wlr_drm_lease_device_v1::connectors + struct wl_list link; // wlr_drm_lease_device_v1.connectors }; struct wlr_drm_lease_request_v1 { @@ -76,7 +76,7 @@ struct wlr_drm_lease_request_v1 { bool invalid; - struct wl_list link; // wlr_drm_lease_device_v1::requests + struct wl_list link; // wlr_drm_lease_device_v1.requests }; struct wlr_drm_lease_v1 { @@ -97,7 +97,8 @@ struct wlr_drm_lease_v1 { /** * Creates a DRM lease manager. A DRM lease device will be created for each - * DRM backend supplied in case of a wlr_multi_backend. + * DRM backend supplied in case of a struct wlr_multi_backend. + * * Returns NULL if no DRM backend is supplied. */ struct wlr_drm_lease_v1_manager *wlr_drm_lease_v1_manager_create( @@ -105,6 +106,7 @@ struct wlr_drm_lease_v1_manager *wlr_drm_lease_v1_manager_create( /** * Offers a wlr_output for lease. + * * Returns false if the output can't be offered to lease. */ bool wlr_drm_lease_v1_manager_offer_output( @@ -120,7 +122,7 @@ void wlr_drm_lease_v1_manager_withdraw_output( /** * Grants a client's lease request. The lease device will then provision the * DRM lease and transfer the file descriptor to the client. After calling this, - * each wlr_output leased is destroyed, and will be re-issued through + * each struct wlr_output leased is destroyed, and will be re-issued through * wlr_backend.events.new_outputs when the lease is revoked. * * This will return NULL without leasing any resources if the lease is invalid; diff --git a/include/wlr/types/wlr_export_dmabuf_v1.h b/include/wlr/types/wlr_export_dmabuf_v1.h index 344e6cbf..39e83be7 100644 --- a/include/wlr/types/wlr_export_dmabuf_v1.h +++ b/include/wlr/types/wlr_export_dmabuf_v1.h @@ -15,7 +15,7 @@ struct wlr_export_dmabuf_manager_v1 { struct wl_global *global; - struct wl_list frames; // wlr_export_dmabuf_frame_v1::link + struct wl_list frames; // wlr_export_dmabuf_frame_v1.link struct wl_listener display_destroy; @@ -27,7 +27,7 @@ struct wlr_export_dmabuf_manager_v1 { struct wlr_export_dmabuf_frame_v1 { struct wl_resource *resource; struct wlr_export_dmabuf_manager_v1 *manager; - struct wl_list link; // wlr_export_dmabuf_manager_v1::frames + struct wl_list link; // wlr_export_dmabuf_manager_v1.frames struct wlr_output *output; diff --git a/include/wlr/types/wlr_foreign_toplevel_management_v1.h b/include/wlr/types/wlr_foreign_toplevel_management_v1.h index d9030b2e..c4abcb3d 100644 --- a/include/wlr/types/wlr_foreign_toplevel_management_v1.h +++ b/include/wlr/types/wlr_foreign_toplevel_management_v1.h @@ -15,8 +15,8 @@ struct wlr_foreign_toplevel_manager_v1 { struct wl_event_loop *event_loop; struct wl_global *global; - struct wl_list resources; // wl_resource_get_link - struct wl_list toplevels; // wlr_foreign_toplevel_handle_v1::link + struct wl_list resources; // wl_resource_get_link() + struct wl_list toplevels; // wlr_foreign_toplevel_handle_v1.link struct wl_listener display_destroy; @@ -35,7 +35,7 @@ enum wlr_foreign_toplevel_handle_v1_state { }; struct wlr_foreign_toplevel_handle_v1_output { - struct wl_list link; // wlr_foreign_toplevel_handle_v1::outputs + struct wl_list link; // wlr_foreign_toplevel_handle_v1.outputs struct wlr_output *output; struct wlr_foreign_toplevel_handle_v1 *toplevel; @@ -54,21 +54,21 @@ struct wlr_foreign_toplevel_handle_v1 { char *title; char *app_id; struct wlr_foreign_toplevel_handle_v1 *parent; - struct wl_list outputs; // wlr_foreign_toplevel_v1_output - uint32_t state; // wlr_foreign_toplevel_v1_state + struct wl_list outputs; // wlr_foreign_toplevel_v1_output.link + uint32_t state; // enum wlr_foreign_toplevel_v1_state struct { - // wlr_foreign_toplevel_handle_v1_maximized_event + // struct wlr_foreign_toplevel_handle_v1_maximized_event struct wl_signal request_maximize; - //wlr_foreign_toplevel_handle_v1_minimized_event + // struct wlr_foreign_toplevel_handle_v1_minimized_event struct wl_signal request_minimize; - //wlr_foreign_toplevel_handle_v1_activated_event + // struct wlr_foreign_toplevel_handle_v1_activated_event struct wl_signal request_activate; - //wlr_foreign_toplevel_handle_v1_fullscreen_event + // struct wlr_foreign_toplevel_handle_v1_fullscreen_event struct wl_signal request_fullscreen; struct wl_signal request_close; - //wlr_foreign_toplevel_handle_v1_set_rectangle_event + // struct wlr_foreign_toplevel_handle_v1_set_rectangle_event struct wl_signal set_rectangle; struct wl_signal destroy; } events; @@ -108,12 +108,14 @@ struct wlr_foreign_toplevel_manager_v1 *wlr_foreign_toplevel_manager_v1_create( struct wlr_foreign_toplevel_handle_v1 *wlr_foreign_toplevel_handle_v1_create( struct wlr_foreign_toplevel_manager_v1 *manager); -/* Destroy the given toplevel handle, sending the closed event to any +/** + * Destroy the given toplevel handle, sending the closed event to any * client. Also, if the destroyed toplevel is set as a parent of any * other valid toplevel, clients still holding a handle to both are * sent a parent signal with NULL parent. If this is not desired, the * caller should ensure that any child toplevels are destroyed before - * the parent. */ + * the parent. + */ void wlr_foreign_toplevel_handle_v1_destroy( struct wlr_foreign_toplevel_handle_v1 *toplevel); @@ -136,11 +138,13 @@ void wlr_foreign_toplevel_handle_v1_set_activated( void wlr_foreign_toplevel_handle_v1_set_fullscreen( struct wlr_foreign_toplevel_handle_v1* toplevel, bool fullscreen); -/* Set the parent of a toplevel. If the parent changed from its previous +/** + * Set the parent of a toplevel. If the parent changed from its previous * value, also sends a parent event to all clients that hold handles to * both toplevel and parent (no message is sent to clients that have * previously destroyed their parent handle). NULL is allowed as the - * parent, meaning no parent exists. */ + * parent, meaning no parent exists. + */ void wlr_foreign_toplevel_handle_v1_set_parent( struct wlr_foreign_toplevel_handle_v1 *toplevel, struct wlr_foreign_toplevel_handle_v1 *parent); diff --git a/include/wlr/types/wlr_fullscreen_shell_v1.h b/include/wlr/types/wlr_fullscreen_shell_v1.h index ea8057f1..4e5b2cfe 100644 --- a/include/wlr/types/wlr_fullscreen_shell_v1.h +++ b/include/wlr/types/wlr_fullscreen_shell_v1.h @@ -17,7 +17,7 @@ struct wlr_fullscreen_shell_v1 { struct { struct wl_signal destroy; - // wlr_fullscreen_shell_v1_present_surface_event + // struct wlr_fullscreen_shell_v1_present_surface_event struct wl_signal present_surface; } events; diff --git a/include/wlr/types/wlr_gamma_control_v1.h b/include/wlr/types/wlr_gamma_control_v1.h index b247bae3..02557148 100644 --- a/include/wlr/types/wlr_gamma_control_v1.h +++ b/include/wlr/types/wlr_gamma_control_v1.h @@ -5,7 +5,7 @@ struct wlr_gamma_control_manager_v1 { struct wl_global *global; - struct wl_list controls; // wlr_gamma_control_v1::link + struct wl_list controls; // wlr_gamma_control_v1.link struct wl_listener display_destroy; diff --git a/include/wlr/types/wlr_idle.h b/include/wlr/types/wlr_idle.h index 8e89a341..0e110180 100644 --- a/include/wlr/types/wlr_idle.h +++ b/include/wlr/types/wlr_idle.h @@ -23,7 +23,7 @@ struct wlr_idle { struct wl_global *global; - struct wl_list idle_timers; // wlr_idle_timeout::link + struct wl_list idle_timers; // wlr_idle_timeout.link struct wl_event_loop *event_loop; bool enabled; diff --git a/include/wlr/types/wlr_idle_inhibit_v1.h b/include/wlr/types/wlr_idle_inhibit_v1.h index 59ec83ff..3127cfdf 100644 --- a/include/wlr/types/wlr_idle_inhibit_v1.h +++ b/include/wlr/types/wlr_idle_inhibit_v1.h @@ -24,7 +24,7 @@ */ struct wlr_idle_inhibit_manager_v1 { - struct wl_list inhibitors; // wlr_idle_inhibit_inhibitor_v1::link + struct wl_list inhibitors; // wlr_idle_inhibit_inhibitor_v1.link struct wl_global *global; struct wl_listener display_destroy; @@ -42,7 +42,7 @@ struct wlr_idle_inhibitor_v1 { struct wl_resource *resource; struct wl_listener surface_destroy; - struct wl_list link; // wlr_idle_inhibit_manager_v1::inhibitors; + struct wl_list link; // wlr_idle_inhibit_manager_v1.inhibitors struct { struct wl_signal destroy; diff --git a/include/wlr/types/wlr_input_method_v2.h b/include/wlr/types/wlr_input_method_v2.h index e4401d29..316cecd5 100644 --- a/include/wlr/types/wlr_input_method_v2.h +++ b/include/wlr/types/wlr_input_method_v2.h @@ -51,10 +51,10 @@ struct wlr_input_method_v2 { struct wl_listener seat_client_destroy; struct { - struct wl_signal commit; // (struct wlr_input_method_v2*) - struct wl_signal new_popup_surface; // (struct wlr_input_popup_surface_v2*) - struct wl_signal grab_keyboard; // (struct wlr_input_method_keyboard_grab_v2*) - struct wl_signal destroy; // (struct wlr_input_method_v2*) + struct wl_signal commit; // struct wlr_input_method_v2 * + struct wl_signal new_popup_surface; // struct wlr_input_popup_surface_v2 * + struct wl_signal grab_keyboard; // struct wlr_input_method_keyboard_grab_v2 * + struct wl_signal destroy; // struct wlr_input_method_v2 * } events; }; @@ -87,19 +87,19 @@ struct wlr_input_method_keyboard_grab_v2 { struct wl_listener keyboard_destroy; struct { - struct wl_signal destroy; // (struct wlr_input_method_keyboard_grab_v2*) + struct wl_signal destroy; // struct wlr_input_method_keyboard_grab_v2 * } events; }; struct wlr_input_method_manager_v2 { struct wl_global *global; - struct wl_list input_methods; // struct wlr_input_method_v2*::link + struct wl_list input_methods; // struct wlr_input_method_v2.link struct wl_listener display_destroy; struct { - struct wl_signal input_method; // (struct wlr_input_method_v2*) - struct wl_signal destroy; // (struct wlr_input_method_manager_v2*) + struct wl_signal input_method; // struct wlr_input_method_v2 * + struct wl_signal destroy; // struct wlr_input_method_manager_v2 * } events; }; diff --git a/include/wlr/types/wlr_keyboard.h b/include/wlr/types/wlr_keyboard.h index d8415933..6a7eff81 100644 --- a/include/wlr/types/wlr_keyboard.h +++ b/include/wlr/types/wlr_keyboard.h @@ -73,8 +73,8 @@ struct wlr_keyboard { struct { /** - * The `key` event signals with a `wlr_event_keyboard_key` event that a - * key has been pressed or released on the keyboard. This event is + * The `key` event signals with a struct wlr_event_keyboard_key_event + * that a key has been pressed or released on the keyboard. This event is * emitted before the xkb state of the keyboard has been updated * (including modifiers). */ @@ -82,9 +82,9 @@ struct wlr_keyboard { /** * The `modifiers` event signals that the modifier state of the - * `wlr_keyboard` has been updated. At this time, you can read the - * modifier state of the `wlr_keyboard` and handle the updated state by - * sending it to clients. + * struct wlr_keyboard has been updated. At this time, you can read the + * modifier state of the struct wlr_keyboard and handle the updated + * state by sending it to clients. */ struct wl_signal modifiers; struct wl_signal keymap; diff --git a/include/wlr/types/wlr_keyboard_group.h b/include/wlr/types/wlr_keyboard_group.h index 3906d948..0d5c6a2a 100644 --- a/include/wlr/types/wlr_keyboard_group.h +++ b/include/wlr/types/wlr_keyboard_group.h @@ -14,28 +14,28 @@ struct wlr_keyboard_group { struct wlr_keyboard keyboard; - struct wl_list devices; // keyboard_group_device::link - struct wl_list keys; // keyboard_group_key::link + struct wl_list devices; // keyboard_group_device.link + struct wl_list keys; // keyboard_group_key.link struct { - /* + /** * Sent when a keyboard has entered the group with keys currently * pressed that are not pressed by any other keyboard in the group. The - * data for this signal will be a wl_array containing the key codes. - * This should be used to update the compositor's internal state. + * data for this signal will be a struct wl_array containing the key + * codes. This should be used to update the compositor's internal state. * Bindings should not be triggered based off of these key codes and * they should also not notify any surfaces of the key press. */ struct wl_signal enter; - /* + /** * Sent when a keyboard has left the group with keys currently pressed * that are not pressed by any other keyboard in the group. The data for - * this signal will be a wl_array containing the key codes. This should - * be used to update the compositor's internal state. Bindings should - * not be triggered based off of these key codes. Additionally, surfaces - * should only be notified if they received a corresponding key press - * for the key code. + * this signal will be a struct wl_array containing the key codes. This + * should be used to update the compositor's internal state. Bindings + * should not be triggered based off of these key codes. Additionally, + * surfaces should only be notified if they received a corresponding key + * press for the key code. */ struct wl_signal leave; } events; diff --git a/include/wlr/types/wlr_keyboard_shortcuts_inhibit_v1.h b/include/wlr/types/wlr_keyboard_shortcuts_inhibit_v1.h index e212e0f4..946e75f4 100644 --- a/include/wlr/types/wlr_keyboard_shortcuts_inhibit_v1.h +++ b/include/wlr/types/wlr_keyboard_shortcuts_inhibit_v1.h @@ -23,14 +23,14 @@ */ struct wlr_keyboard_shortcuts_inhibit_manager_v1 { - // wlr_keyboard_shortcuts_inhibitor_v1::link + // wlr_keyboard_shortcuts_inhibitor_v1.link struct wl_list inhibitors; struct wl_global *global; struct wl_listener display_destroy; struct { - struct wl_signal new_inhibitor; // wlr_keyboard_shortcuts_inhibitor_v1 + struct wl_signal new_inhibitor; // struct wlr_keyboard_shortcuts_inhibitor_v1 struct wl_signal destroy; } events; @@ -46,7 +46,7 @@ struct wlr_keyboard_shortcuts_inhibitor_v1 { struct wl_listener surface_destroy; struct wl_listener seat_destroy; - // wlr_keyboard_shortcuts_inhibit_manager_v1::inhibitors + // wlr_keyboard_shortcuts_inhibit_manager_v1.inhibitors struct wl_list link; struct { diff --git a/include/wlr/types/wlr_layer_shell_v1.h b/include/wlr/types/wlr_layer_shell_v1.h index fcb72f24..e97c7311 100644 --- a/include/wlr/types/wlr_layer_shell_v1.h +++ b/include/wlr/types/wlr_layer_shell_v1.h @@ -19,11 +19,11 @@ * wlr_layer_shell_v1 allows clients to arrange themselves in "layers" on the * desktop in accordance with the wlr-layer-shell protocol. When a client is * added, the new_surface signal will be raised and passed a reference to our - * wlr_layer_surface_v1. At this time, the client will have configured the + * struct wlr_layer_surface_v1. At this time, the client will have configured the * surface as it desires, including information like desired anchors and * margins. The compositor should use this information to decide how to arrange * the layer on-screen, then determine the dimensions of the layer and call - * wlr_layer_surface_v1_configure. The client will then attach a buffer and + * wlr_layer_surface_v1_configure(). The client will then attach a buffer and * commit the surface, at which point the wlr_layer_surface_v1 map signal is * raised and the compositor should begin rendering the surface. */ @@ -69,7 +69,7 @@ struct wlr_layer_surface_v1_state { }; struct wlr_layer_surface_v1_configure { - struct wl_list link; // wlr_layer_surface_v1::configure_list + struct wl_list link; // wlr_layer_surface_v1.configure_list uint32_t serial; uint32_t width, height; @@ -80,7 +80,7 @@ struct wlr_layer_surface_v1 { struct wlr_output *output; struct wl_resource *resource; struct wlr_layer_shell_v1 *shell; - struct wl_list popups; // wlr_xdg_popup::link + struct wl_list popups; // wlr_xdg_popup.link char *namespace; @@ -93,9 +93,10 @@ struct wlr_layer_surface_v1 { struct { /** - * The destroy signal indicates that the wlr_layer_surface is about to be - * freed. It is guaranteed that the unmap signal is raised before the destroy - * signal if the layer surface is destroyed while mapped. + * The destroy signal indicates that the struct wlr_layer_surface is + * about to be freed. It is guaranteed that the unmap signal is raised + * before the destroy signal if the layer surface is destroyed while + * mapped. */ struct wl_signal destroy; /** @@ -114,7 +115,8 @@ struct wlr_layer_surface_v1 { struct wl_signal unmap; /** * The new_popup signal is raised when a new popup is created. The data - * parameter passed to the listener is a pointer to the new wlr_xdg_popup. + * parameter passed to the listener is a pointer to the new + * struct wlr_xdg_popup. */ struct wl_signal new_popup; } events; @@ -134,7 +136,7 @@ uint32_t wlr_layer_surface_v1_configure(struct wlr_layer_surface_v1 *surface, /** * Notify the client that the surface has been closed and destroy the - * wlr_layer_surface_v1, rendering the resource inert. + * struct wlr_layer_surface_v1, rendering the resource inert. */ void wlr_layer_surface_v1_destroy(struct wlr_layer_surface_v1 *surface); @@ -178,7 +180,8 @@ struct wlr_surface *wlr_layer_surface_v1_popup_surface_at( struct wlr_layer_surface_v1 *surface, double sx, double sy, double *sub_x, double *sub_y); -/** Get the corresponding wlr_layer_surface_v1 from a resource. +/** + * Get the corresponding struct wlr_layer_surface_v1 from a resource. * * Aborts if the resource doesn't have the correct type. */ diff --git a/include/wlr/types/wlr_linux_dmabuf_v1.h b/include/wlr/types/wlr_linux_dmabuf_v1.h index df89a121..6b5f0d68 100644 --- a/include/wlr/types/wlr_linux_dmabuf_v1.h +++ b/include/wlr/types/wlr_linux_dmabuf_v1.h @@ -35,8 +35,8 @@ struct wlr_dmabuf_v1_buffer { bool wlr_dmabuf_v1_resource_is_buffer(struct wl_resource *buffer_resource); /** - * Returns the wlr_dmabuf_buffer if the given resource was created - * via the linux-dmabuf buffer protocol + * Returns the struct wlr_dmabuf_buffer if the given resource was created + * via the linux-dmabuf buffer protocol. */ struct wlr_dmabuf_v1_buffer *wlr_dmabuf_v1_buffer_from_buffer_resource( struct wl_resource *buffer_resource); @@ -72,7 +72,7 @@ struct wlr_linux_dmabuf_v1 { }; /** - * Create linux-dmabuf interface + * Create linux-dmabuf interface. */ struct wlr_linux_dmabuf_v1 *wlr_linux_dmabuf_v1_create(struct wl_display *display, struct wlr_renderer *renderer); diff --git a/include/wlr/types/wlr_output.h b/include/wlr/types/wlr_output.h index f3a02dee..48b6e6f9 100644 --- a/include/wlr/types/wlr_output.h +++ b/include/wlr/types/wlr_output.h @@ -108,9 +108,9 @@ struct wlr_output_impl; * The `frame` event will be emitted when it is a good time for the compositor * to submit a new frame. * - * To render a new frame, compositors should call `wlr_output_attach_render`, - * render and call `wlr_output_commit`. No rendering should happen outside a - * `frame` event handler or before `wlr_output_attach_render`. + * To render a new frame, compositors should call wlr_output_attach_render(), + * render and call wlr_output_commit(). No rendering should happen outside a + * `frame` event handler or before wlr_output_attach_render(). */ struct wlr_output { const struct wlr_output_impl *impl; @@ -259,7 +259,7 @@ struct wlr_surface; * emit `frame` events. * * Whether an output is enabled is double-buffered state, see - * `wlr_output_commit`. + * wlr_output_commit(). */ void wlr_output_enable(struct wlr_output *output, bool enable); void wlr_output_create_global(struct wlr_output *output); @@ -268,8 +268,8 @@ void wlr_output_destroy_global(struct wlr_output *output); * Initialize the output's rendering subsystem with the provided allocator and * renderer. Can only be called once. * - * Call this function prior to any call to wlr_output_attach_render, - * wlr_output_commit or wlr_output_cursor_create. + * Call this function prior to any call to wlr_output_attach_render(), + * wlr_output_commit() or wlr_output_cursor_create(). * * The buffer capabilities of the provided must match the capabilities of the * output's backend. Returns false otherwise. @@ -284,7 +284,7 @@ struct wlr_output_mode *wlr_output_preferred_mode(struct wlr_output *output); /** * Sets the output mode. The output needs to be enabled. * - * Mode is double-buffered state, see `wlr_output_commit`. + * Mode is double-buffered state, see wlr_output_commit(). */ void wlr_output_set_mode(struct wlr_output *output, struct wlr_output_mode *mode); @@ -293,14 +293,14 @@ void wlr_output_set_mode(struct wlr_output *output, * Setting `refresh` to zero lets the backend pick a preferred value. The * output needs to be enabled. * - * Custom mode is double-buffered state, see `wlr_output_commit`. + * Custom mode is double-buffered state, see wlr_output_commit(). */ void wlr_output_set_custom_mode(struct wlr_output *output, int32_t width, int32_t height, int32_t refresh); /** * Sets a transform for the output. * - * Transform is double-buffered state, see `wlr_output_commit`. + * Transform is double-buffered state, see wlr_output_commit(). */ void wlr_output_set_transform(struct wlr_output *output, enum wl_output_transform transform); @@ -311,7 +311,7 @@ void wlr_output_set_transform(struct wlr_output *output, * When enabled, compositors can submit frames a little bit later than the * deadline without dropping a frame. * - * Adaptive sync is double-buffered state, see `wlr_output_commit`. + * Adaptive sync is double-buffered state, see wlr_output_commit(). */ void wlr_output_enable_adaptive_sync(struct wlr_output *output, bool enabled); /** @@ -323,17 +323,17 @@ void wlr_output_enable_adaptive_sync(struct wlr_output *output, bool enabled); * hardware and software permit this. * * This only affects the format of the output buffer used when rendering, - * as with `wlr_output_attach_render`. It has no impact on the cursor buffer + * as with wlr_output_attach_render(). It has no impact on the cursor buffer * format, or on the formats supported for direct scan-out (see also - * `wlr_output_attach_buffer`). + * wlr_output_attach_buffer()). * - * This format is double-buffered state, see `wlr_output_commit`. + * This format is double-buffered state, see wlr_output_commit(). */ void wlr_output_set_render_format(struct wlr_output *output, uint32_t format); /** * Sets a scale for the output. * - * Scale is double-buffered state, see `wlr_output_commit`. + * Scale is double-buffered state, see wlr_output_commit(). */ void wlr_output_set_scale(struct wlr_output *output, float scale); void wlr_output_set_subpixel(struct wlr_output *output, @@ -370,22 +370,22 @@ void wlr_output_effective_resolution(struct wlr_output *output, /** * Attach the renderer's buffer to the output. Compositors must call this * function before rendering. After they are done rendering, they should call - * `wlr_output_commit` to submit the new frame. The output needs to be + * wlr_output_commit() to submit the new frame. The output needs to be * enabled. * * If non-NULL, `buffer_age` is set to the drawing buffer age in number of * frames or -1 if unknown. This is useful for damage tracking. * * If the compositor decides not to render after calling this function, it - * must call wlr_output_rollback. + * must call wlr_output_rollback(). */ bool wlr_output_attach_render(struct wlr_output *output, int *buffer_age); /** - * Attach a buffer to the output. Compositors should call `wlr_output_commit` + * Attach a buffer to the output. Compositors should call wlr_output_commit() * to submit the new frame. The output needs to be enabled. * * Not all backends support direct scan-out on all buffers. Compositors can - * check whether a buffer is supported by calling `wlr_output_test`. + * check whether a buffer is supported by calling wlr_output_test(). */ void wlr_output_attach_buffer(struct wlr_output *output, struct wlr_buffer *buffer); @@ -409,14 +409,14 @@ void wlr_output_set_damage(struct wlr_output *output, pixman_region32_t *damage); /** * Test whether the pending output state would be accepted by the backend. If - * this function returns true, `wlr_output_commit` can only fail due to a + * this function returns true, wlr_output_commit() can only fail due to a * runtime error. * * This function doesn't mutate the pending state. */ bool wlr_output_test(struct wlr_output *output); /** - * Commit the pending output state. If `wlr_output_attach_render` has been + * Commit the pending output state. If wlr_output_attach_render() has been * called, the pending frame will be submitted for display and a `frame` event * will be scheduled. * @@ -439,11 +439,11 @@ size_t wlr_output_get_gamma_size(struct wlr_output *output); /** * Sets the gamma table for this output. `r`, `g` and `b` are gamma ramps for * red, green and blue. `size` is the length of the ramps and must not exceed - * the value returned by `wlr_output_get_gamma_size`. + * the value returned by wlr_output_get_gamma_size(). * * Providing zero-sized ramps resets the gamma table. * - * The gamma table is double-buffered state, see `wlr_output_commit`. + * The gamma table is double-buffered state, see wlr_output_commit(). */ void wlr_output_set_gamma(struct wlr_output *output, size_t size, const uint16_t *r, const uint16_t *g, const uint16_t *b); diff --git a/include/wlr/types/wlr_output_damage.h b/include/wlr/types/wlr_output_damage.h index ba5c88df..51a5be8c 100644 --- a/include/wlr/types/wlr_output_damage.h +++ b/include/wlr/types/wlr_output_damage.h @@ -29,9 +29,9 @@ struct wlr_box; * to submit a new frame. * * To render a new frame, compositors should call - * `wlr_output_damage_attach_render`, render and call `wlr_output_commit`. No + * wlr_output_damage_attach_render(), render and call wlr_output_commit(). No * rendering should happen outside a `frame` event handler or before - * `wlr_output_damage_attach_render`. + * wlr_output_damage_attach_render(). */ struct wlr_output_damage { struct wlr_output *output; @@ -64,7 +64,7 @@ void wlr_output_damage_destroy(struct wlr_output_damage *output_damage); /** * Attach the renderer's buffer to the output. Compositors must call this * function before rendering. After they are done rendering, they should call - * `wlr_output_set_damage` and `wlr_output_commit` to submit the new frame. + * wlr_output_set_damage() and wlr_output_commit() to submit the new frame. * * `needs_frame` will be set to true if a frame should be submitted. `damage` * will be set to the region of the output that needs to be repainted, in diff --git a/include/wlr/types/wlr_output_layout.h b/include/wlr/types/wlr_output_layout.h index 3cb6e1e2..c61e1938 100644 --- a/include/wlr/types/wlr_output_layout.h +++ b/include/wlr/types/wlr_output_layout.h @@ -18,10 +18,10 @@ struct wlr_box; /** * Helper to arrange outputs in a 2D coordinate space. The output effective - * resolution is used, see wlr_output_effective_resolution. + * resolution is used, see wlr_output_effective_resolution(). * * Outputs added to the output layout are automatically exposed to clients (see - * wlr_output_create_global). They are no longer exposed when removed from the + * wlr_output_create_global()). They are no longer exposed when removed from the * layout. */ struct wlr_output_layout { @@ -115,7 +115,7 @@ void wlr_output_layout_get_box(struct wlr_output_layout *layout, * sensible location in the layout. The coordinates of the output in the layout * may adjust dynamically when the layout changes. If the output is already in * the layout, it will become auto configured. If the position of the output is -* set such as with `wlr_output_layout_move()`, the output will become manually +* set such as with wlr_output_layout_move(), the output will become manually * configured. */ void wlr_output_layout_add_auto(struct wlr_output_layout *layout, diff --git a/include/wlr/types/wlr_output_management_v1.h b/include/wlr/types/wlr_output_management_v1.h index c0551ac1..0b8d8c20 100644 --- a/include/wlr/types/wlr_output_management_v1.h +++ b/include/wlr/types/wlr_output_management_v1.h @@ -16,9 +16,9 @@ struct wlr_output_manager_v1 { struct wl_display *display; struct wl_global *global; - struct wl_list resources; // wl_resource_get_link + struct wl_list resources; // wl_resource_get_link() - struct wl_list heads; // wlr_output_head_v1::link + struct wl_list heads; // wlr_output_head_v1.link uint32_t serial; bool current_configuration_dirty; @@ -33,8 +33,8 @@ struct wlr_output_manager_v1 { * event data). That is, the compositor is responsible for destroying * the configuration. */ - struct wl_signal apply; // wlr_output_configuration_v1 - struct wl_signal test; // wlr_output_configuration_v1 + struct wl_signal apply; // struct wlr_output_configuration_v1 + struct wl_signal test; // struct wlr_output_configuration_v1 struct wl_signal destroy; } events; @@ -61,16 +61,16 @@ struct wlr_output_head_v1_state { struct wlr_output_head_v1 { struct wlr_output_head_v1_state state; struct wlr_output_manager_v1 *manager; - struct wl_list link; // wlr_output_manager_v1::heads + struct wl_list link; // wlr_output_manager_v1.heads - struct wl_list resources; // wl_resource_get_link - struct wl_list mode_resources; // wl_resource_get_link + struct wl_list resources; // wl_resource_get_link() + struct wl_list mode_resources; // wl_resource_get_link() struct wl_listener output_destroy; }; struct wlr_output_configuration_v1 { - struct wl_list heads; // wlr_output_configuration_head_v1::link + struct wl_list heads; // wlr_output_configuration_head_v1.link // client state struct wlr_output_manager_v1 *manager; @@ -83,7 +83,7 @@ struct wlr_output_configuration_v1 { struct wlr_output_configuration_head_v1 { struct wlr_output_head_v1_state state; struct wlr_output_configuration_v1 *config; - struct wl_list link; // wlr_output_configuration_v1::heads + struct wl_list link; // wlr_output_configuration_v1.heads // client state struct wl_resource *resource; // can be NULL if finalized or disabled @@ -93,7 +93,7 @@ struct wlr_output_configuration_head_v1 { /** * Create a new output manager. The compositor is responsible for calling - * `wlr_output_manager_v1_set_configuration` whenever the current output + * wlr_output_manager_v1_set_configuration() whenever the current output * configuration changes. */ struct wlr_output_manager_v1 *wlr_output_manager_v1_create( @@ -111,8 +111,8 @@ void wlr_output_manager_v1_set_configuration( /** * Create a new, empty output configuration. Compositors should add current head - * status with `wlr_output_configuration_head_v1_create`. They can then call - * `wlr_output_manager_v1_set_configuration`. + * status with wlr_output_configuration_head_v1_create(). They can then call + * wlr_output_manager_v1_set_configuration(). */ struct wlr_output_configuration_v1 *wlr_output_configuration_v1_create(void); void wlr_output_configuration_v1_destroy( diff --git a/include/wlr/types/wlr_output_power_management_v1.h b/include/wlr/types/wlr_output_power_management_v1.h index 23ce814a..688e37a4 100644 --- a/include/wlr/types/wlr_output_power_management_v1.h +++ b/include/wlr/types/wlr_output_power_management_v1.h @@ -6,12 +6,12 @@ struct wlr_output_power_manager_v1 { struct wl_global *global; - struct wl_list output_powers; // wlr_output_power_v1::link + struct wl_list output_powers; // wlr_output_power_v1.link struct wl_listener display_destroy; struct { - struct wl_signal set_mode; // wlr_output_power_v1_set_mode_event + struct wl_signal set_mode; // struct wlr_output_power_v1_set_mode_event struct wl_signal destroy; } events; @@ -22,7 +22,7 @@ struct wlr_output_power_v1 { struct wl_resource *resource; struct wlr_output *output; struct wlr_output_power_manager_v1 *manager; - struct wl_list link; + struct wl_list link; // wlr_output_power_manager_v1.output_powers struct wl_listener output_destroy_listener; struct wl_listener output_commit_listener; diff --git a/include/wlr/types/wlr_pointer_constraints_v1.h b/include/wlr/types/wlr_pointer_constraints_v1.h index 90438729..21280ff2 100644 --- a/include/wlr/types/wlr_pointer_constraints_v1.h +++ b/include/wlr/types/wlr_pointer_constraints_v1.h @@ -53,7 +53,7 @@ struct wlr_pointer_constraint_v1 { struct wl_listener surface_destroy; struct wl_listener seat_destroy; - struct wl_list link; // wlr_pointer_constraints_v1::constraints + struct wl_list link; // wlr_pointer_constraints_v1.constraints struct { /** @@ -69,13 +69,13 @@ struct wlr_pointer_constraint_v1 { struct wlr_pointer_constraints_v1 { struct wl_global *global; - struct wl_list constraints; // wlr_pointer_constraint_v1::link + struct wl_list constraints; // wlr_pointer_constraint_v1.link struct { /** * Called when a new pointer constraint is created. * - * data: struct wlr_pointer_constraint_v1 * + * The data pointer is a struct wlr_pointer_constraint_v1. */ struct wl_signal new_constraint; } events; diff --git a/include/wlr/types/wlr_pointer_gestures_v1.h b/include/wlr/types/wlr_pointer_gestures_v1.h index b05b1a30..5510ce21 100644 --- a/include/wlr/types/wlr_pointer_gestures_v1.h +++ b/include/wlr/types/wlr_pointer_gestures_v1.h @@ -16,9 +16,9 @@ struct wlr_surface; struct wlr_pointer_gestures_v1 { struct wl_global *global; - struct wl_list swipes; // wl_resource_get_link - struct wl_list pinches; // wl_resource_get_link - struct wl_list holds; // wl_resource_get_link + struct wl_list swipes; // wl_resource_get_link() + struct wl_list pinches; // wl_resource_get_link() + struct wl_list holds; // wl_resource_get_link() struct wl_listener display_destroy; diff --git a/include/wlr/types/wlr_presentation_time.h b/include/wlr/types/wlr_presentation_time.h index b1dc1868..48bef659 100644 --- a/include/wlr/types/wlr_presentation_time.h +++ b/include/wlr/types/wlr_presentation_time.h @@ -31,10 +31,10 @@ struct wlr_presentation { }; struct wlr_presentation_feedback { - struct wl_list resources; // wl_resource_get_link + struct wl_list resources; // wl_resource_get_link() - // Only when the wlr_presentation_surface_sampled_on_output helper has been - // called + // Only when the wlr_presentation_surface_sampled_on_output() helper has + // been called. struct wlr_output *output; bool output_committed; uint32_t output_commit_seq; @@ -50,7 +50,7 @@ struct wlr_presentation_event { uint32_t tv_nsec; uint32_t refresh; uint64_t seq; - uint32_t flags; // wp_presentation_feedback_kind + uint32_t flags; // enum wp_presentation_feedback_kind }; struct wlr_backend; @@ -64,8 +64,8 @@ struct wlr_presentation *wlr_presentation_create(struct wl_display *display, * contents (e.g. when rendering the surface's current texture, when * referencing its current buffer, or when directly scanning out its current * buffer). A wlr_presentation_feedback is returned. The compositor should call - * wlr_presentation_feedback_send_presented if this content has been displayed, - * then wlr_presentation_feedback_destroy. + * wlr_presentation_feedback_send_presented() if this content has been displayed, + * then wlr_presentation_feedback_destroy(). * * NULL is returned if the client hasn't requested presentation feedback for * this surface. @@ -79,7 +79,7 @@ void wlr_presentation_feedback_destroy( struct wlr_presentation_feedback *feedback); /** - * Fill a wlr_presentation_event from a wlr_output_event_present. + * Fill a wlr_presentation_event from a struct wlr_output_event_present. */ void wlr_presentation_event_from_output(struct wlr_presentation_event *event, const struct wlr_output_event_present *output_event); @@ -87,9 +87,9 @@ void wlr_presentation_event_from_output(struct wlr_presentation_event *event, /** * Mark the current surface's buffer as sampled on the given output. * - * Instead of calling wlr_presentation_surface_sampled and managing the - * wlr_presentation_feedback itself, the compositor can call this function - * before a wlr_output_commit call to indicate that the surface's current + * Instead of calling wlr_presentation_surface_sampled() and managing the + * struct wlr_presentation_feedback itself, the compositor can call this function + * before a wlr_output_commit() call to indicate that the surface's current * contents will be displayed on the output. */ void wlr_presentation_surface_sampled_on_output( diff --git a/include/wlr/types/wlr_primary_selection_v1.h b/include/wlr/types/wlr_primary_selection_v1.h index 7434d831..78b542a0 100644 --- a/include/wlr/types/wlr_primary_selection_v1.h +++ b/include/wlr/types/wlr_primary_selection_v1.h @@ -14,7 +14,7 @@ struct wlr_primary_selection_v1_device_manager { struct wl_global *global; - struct wl_list devices; // wlr_primary_selection_v1_device::link + struct wl_list devices; // wlr_primary_selection_v1_device.link struct wl_listener display_destroy; @@ -31,10 +31,10 @@ struct wlr_primary_selection_v1_device_manager { struct wlr_primary_selection_v1_device { struct wlr_primary_selection_v1_device_manager *manager; struct wlr_seat *seat; - struct wl_list link; // wlr_primary_selection_v1_device_manager::devices - struct wl_list resources; // wl_resource_get_link + struct wl_list link; // wlr_primary_selection_v1_device_manager.devices + struct wl_list resources; // wl_resource_get_link() - struct wl_list offers; // wl_resource_get_link + struct wl_list offers; // wl_resource_get_link() struct wl_listener seat_destroy; struct wl_listener seat_focus_change; diff --git a/include/wlr/types/wlr_relative_pointer_v1.h b/include/wlr/types/wlr_relative_pointer_v1.h index 59dd98d6..fcd44d52 100644 --- a/include/wlr/types/wlr_relative_pointer_v1.h +++ b/include/wlr/types/wlr_relative_pointer_v1.h @@ -23,11 +23,11 @@ */ struct wlr_relative_pointer_manager_v1 { struct wl_global *global; - struct wl_list relative_pointers; // wlr_relative_pointer_v1::link + struct wl_list relative_pointers; // wlr_relative_pointer_v1.link struct { struct wl_signal destroy; - struct wl_signal new_relative_pointer; // wlr_relative_pointer_v1 + struct wl_signal new_relative_pointer; // struct wlr_relative_pointer_v1 } events; struct wl_listener display_destroy_listener; @@ -45,7 +45,7 @@ struct wlr_relative_pointer_v1 { struct wl_resource *resource; struct wl_resource *pointer_resource; struct wlr_seat *seat; - struct wl_list link; // wlr_relative_pointer_manager_v1::relative_pointers + struct wl_list link; // wlr_relative_pointer_manager_v1.relative_pointers struct { struct wl_signal destroy; diff --git a/include/wlr/types/wlr_scene.h b/include/wlr/types/wlr_scene.h index 0802014e..0e3857d5 100644 --- a/include/wlr/types/wlr_scene.h +++ b/include/wlr/types/wlr_scene.h @@ -258,7 +258,7 @@ struct wlr_scene *wlr_scene_create(void); * Handle presentation feedback for all surfaces in the scene, assuming that * scene outputs and the scene rendering functions are used. * - * Asserts that a wlr_presentation hasn't already been set for the scene. + * Asserts that a struct wlr_presentation hasn't already been set for the scene. */ void wlr_scene_set_presentation(struct wlr_scene *scene, struct wlr_presentation *presentation); @@ -273,7 +273,7 @@ struct wlr_scene_tree *wlr_scene_tree_create(struct wlr_scene_node *parent); * * The child sub-surfaces are ignored. * - * wlr_surface_send_enter()/wlr_surface_send_leave() will be called + * wlr_surface_send_enter() and wlr_surface_send_leave() will be called * automatically based on the position of the surface and outputs in * the scene. */ @@ -283,7 +283,7 @@ struct wlr_scene_surface *wlr_scene_surface_create(struct wlr_scene_node *parent struct wlr_scene_buffer *wlr_scene_buffer_from_node(struct wlr_scene_node *node); /** - * If this buffer is backed by a surface, then the wlr_scene_surface is + * If this buffer is backed by a surface, then the struct wlr_scene_surface is * returned. If not, NULL will be returned. */ struct wlr_scene_surface *wlr_scene_surface_from_buffer( @@ -383,7 +383,7 @@ void wlr_scene_output_set_position(struct wlr_scene_output *scene_output, bool wlr_scene_output_commit(struct wlr_scene_output *scene_output); /** * Call wlr_surface_send_frame_done() on all surfaces in the scene rendered by - * wlr_scene_output_commit() for which wlr_scene_surface->primary_output + * wlr_scene_output_commit() for which wlr_scene_surface.primary_output * matches the given scene_output. */ void wlr_scene_output_send_frame_done(struct wlr_scene_output *scene_output, @@ -396,7 +396,7 @@ void wlr_scene_output_send_frame_done(struct wlr_scene_output *scene_output, void wlr_scene_output_for_each_buffer(struct wlr_scene_output *scene_output, wlr_scene_buffer_iterator_func_t iterator, void *user_data); /** - * Get a scene-graph output from a wlr_output. + * Get a scene-graph output from a struct wlr_output. * * If the output hasn't been added to the scene-graph, returns NULL. */ diff --git a/include/wlr/types/wlr_screencopy_v1.h b/include/wlr/types/wlr_screencopy_v1.h index 9947b015..50e398e7 100644 --- a/include/wlr/types/wlr_screencopy_v1.h +++ b/include/wlr/types/wlr_screencopy_v1.h @@ -15,7 +15,7 @@ struct wlr_screencopy_manager_v1 { struct wl_global *global; - struct wl_list frames; // wlr_screencopy_frame_v1::link + struct wl_list frames; // wlr_screencopy_frame_v1.link struct wl_listener display_destroy; @@ -35,7 +35,7 @@ struct wlr_screencopy_v1_client { struct wlr_screencopy_frame_v1 { struct wl_resource *resource; struct wlr_screencopy_v1_client *client; - struct wl_list link; + struct wl_list link; // wlr_screencopy_manager_v1.frames enum wl_shm_format format; uint32_t fourcc; diff --git a/include/wlr/types/wlr_seat.h b/include/wlr/types/wlr_seat.h index 1946873a..8c1d4661 100644 --- a/include/wlr/types/wlr_seat.h +++ b/include/wlr/types/wlr_seat.h @@ -32,7 +32,7 @@ struct wlr_serial_ringset { /** * Contains state for a single client's bound wl_seat resource and can be used * to issue input events to that client. The lifetime of these objects is - * managed by wlr_seat; some may be NULL. + * managed by struct wlr_seat; some may be NULL. */ struct wlr_seat_client { struct wl_client *client; @@ -127,7 +127,7 @@ struct wlr_touch_grab_interface { }; /** - * Passed to `wlr_seat_touch_start_grab()` to start a grab of the touch device. + * Passed to wlr_seat_touch_start_grab() to start a grab of the touch device. * The grabber is responsible for handling touch events for the seat. */ struct wlr_seat_touch_grab { @@ -137,7 +137,7 @@ struct wlr_seat_touch_grab { }; /** - * Passed to `wlr_seat_keyboard_start_grab()` to start a grab of the keyboard. + * Passed to wlr_seat_keyboard_start_grab() to start a grab of the keyboard. * The grabber is responsible for handling keyboard events for the seat. */ struct wlr_seat_keyboard_grab { @@ -147,7 +147,7 @@ struct wlr_seat_keyboard_grab { }; /** - * Passed to `wlr_seat_pointer_start_grab()` to start a grab of the pointer. The + * Passed to wlr_seat_pointer_start_grab() to start a grab of the pointer. The * grabber is responsible for handling pointer events for the seat. */ struct wlr_seat_pointer_grab { @@ -179,7 +179,7 @@ struct wlr_seat_pointer_state { struct wl_listener surface_destroy; struct { - struct wl_signal focus_change; // wlr_seat_pointer_focus_change_event + struct wl_signal focus_change; // struct wlr_seat_pointer_focus_change_event } events; }; @@ -201,13 +201,13 @@ struct wlr_seat_keyboard_state { struct wlr_seat_keyboard_grab *default_grab; struct { - struct wl_signal focus_change; // wlr_seat_keyboard_focus_change_event + struct wl_signal focus_change; // struct wlr_seat_keyboard_focus_change_event } events; }; struct wlr_seat_touch_state { struct wlr_seat *seat; - struct wl_list touch_points; // wlr_touch_point::link + struct wl_list touch_points; // wlr_touch_point.link uint32_t grab_serial; uint32_t grab_id; @@ -230,7 +230,7 @@ struct wlr_seat { struct wlr_data_source *selection_source; uint32_t selection_serial; - struct wl_list selection_offers; // wlr_data_offer::link + struct wl_list selection_offers; // wlr_data_offer.link struct wlr_primary_selection_source *primary_selection_source; uint32_t primary_selection_serial; @@ -239,7 +239,7 @@ struct wlr_seat { struct wlr_drag *drag; struct wlr_data_source *drag_source; uint32_t drag_serial; - struct wl_list drag_offers; // wlr_data_offer::link + struct wl_list drag_offers; // wlr_data_offer.link struct wlr_seat_pointer_state pointer_state; struct wlr_seat_keyboard_state keyboard_state; @@ -260,26 +260,26 @@ struct wlr_seat { struct wl_signal touch_grab_begin; struct wl_signal touch_grab_end; - // wlr_seat_pointer_request_set_cursor_event + // struct wlr_seat_pointer_request_set_cursor_event struct wl_signal request_set_cursor; // Called when an application _wants_ to set the selection (user copies some data). - // Compositors should listen to this event and call wlr_seat_set_selection + // Compositors should listen to this event and call wlr_seat_set_selection() // if they want to accept the client's request. - struct wl_signal request_set_selection; // wlr_seat_request_set_selection_event + struct wl_signal request_set_selection; // struct wlr_seat_request_set_selection_event // Called after the data source is set for the selection. struct wl_signal set_selection; // Called when an application _wants_ to set the primary selection (user selects some data). - // Compositors should listen to this event and call wlr_seat_set_primary_selection + // Compositors should listen to this event and call wlr_seat_set_primary_selection() // if they want to accept the client's request. - struct wl_signal request_set_primary_selection; // wlr_seat_request_set_primary_selection_event + struct wl_signal request_set_primary_selection; // struct wlr_seat_request_set_primary_selection_event // Called after the primary selection source object is set. struct wl_signal set_primary_selection; - // wlr_seat_request_start_drag_event + // struct wlr_seat_request_start_drag_event struct wl_signal request_start_drag; - struct wl_signal start_drag; // wlr_drag + struct wl_signal start_drag; // struct wlr_drag struct wl_signal destroy; } events; @@ -322,16 +322,16 @@ struct wlr_seat_keyboard_focus_change_event { }; /** - * Allocates a new wlr_seat and adds a wl_seat global to the display. + * Allocates a new struct wlr_seat and adds a wl_seat global to the display. */ struct wlr_seat *wlr_seat_create(struct wl_display *display, const char *name); /** - * Destroys a wlr_seat, removes its wl_seat global and clears focus for all + * Destroys a seat, removes its wl_seat global and clears focus for all * devices belonging to the seat. */ void wlr_seat_destroy(struct wlr_seat *wlr_seat); /** - * Gets a wlr_seat_client for the specified client, or returns NULL if no + * Gets a struct wlr_seat_client for the specified client, or returns NULL if no * client is bound for that client. */ struct wlr_seat_client *wlr_seat_client_for_wl_client(struct wlr_seat *wlr_seat, @@ -359,7 +359,7 @@ bool wlr_seat_pointer_surface_has_focus(struct wlr_seat *wlr_seat, * focused surface for the pointer. This will send a leave event to the last * surface that was entered. Coordinates for the enter event are surface-local. * This function does not respect pointer grabs: you probably want - * `wlr_seat_pointer_notify_enter()` instead. + * wlr_seat_pointer_notify_enter() instead. */ void wlr_seat_pointer_enter(struct wlr_seat *wlr_seat, struct wlr_surface *surface, double sx, double sy); @@ -367,14 +367,14 @@ void wlr_seat_pointer_enter(struct wlr_seat *wlr_seat, /** * Clear the focused surface for the pointer and leave all entered surfaces. * This function does not respect pointer grabs: you probably want - * `wlr_seat_pointer_notify_clear_focus()` instead. + * wlr_seat_pointer_notify_clear_focus() instead. */ void wlr_seat_pointer_clear_focus(struct wlr_seat *wlr_seat); /** * Send a motion event to the surface with pointer focus. Coordinates for the * motion event are surface-local. This function does not respect pointer grabs: - * you probably want `wlr_seat_pointer_notify_motion()` instead. + * you probably want wlr_seat_pointer_notify_motion() instead. */ void wlr_seat_pointer_send_motion(struct wlr_seat *wlr_seat, uint32_t time_msec, double sx, double sy); @@ -382,7 +382,7 @@ void wlr_seat_pointer_send_motion(struct wlr_seat *wlr_seat, uint32_t time_msec, /** * Send a button event to the surface with pointer focus. Coordinates for the * button event are surface-local. Returns the serial. This function does not - * respect pointer grabs: you probably want `wlr_seat_pointer_notify_button()` + * respect pointer grabs: you probably want wlr_seat_pointer_notify_button() * instead. */ uint32_t wlr_seat_pointer_send_button(struct wlr_seat *wlr_seat, @@ -390,7 +390,7 @@ uint32_t wlr_seat_pointer_send_button(struct wlr_seat *wlr_seat, /** * Send an axis event to the surface with pointer focus. This function does not - * respect pointer grabs: you probably want `wlr_seat_pointer_notify_axis()` + * respect pointer grabs: you probably want wlr_seat_pointer_notify_axis() * instead. */ void wlr_seat_pointer_send_axis(struct wlr_seat *wlr_seat, uint32_t time_msec, @@ -399,7 +399,7 @@ void wlr_seat_pointer_send_axis(struct wlr_seat *wlr_seat, uint32_t time_msec, /** * Send a frame event to the surface with pointer focus. This function does not - * respect pointer grabs: you probably want `wlr_seat_pointer_notify_frame()` + * respect pointer grabs: you probably want wlr_seat_pointer_notify_frame() * instead. */ void wlr_seat_pointer_send_frame(struct wlr_seat *wlr_seat); @@ -485,7 +485,7 @@ struct wlr_keyboard *wlr_seat_get_keyboard(struct wlr_seat *seat); /** * Send the keyboard key to focused keyboard resources. This function does not - * respect keyboard grabs: you probably want `wlr_seat_keyboard_notify_key()` + * respect keyboard grabs: you probably want wlr_seat_keyboard_notify_key() * instead. */ void wlr_seat_keyboard_send_key(struct wlr_seat *seat, uint32_t time_msec, @@ -494,7 +494,7 @@ void wlr_seat_keyboard_send_key(struct wlr_seat *seat, uint32_t time_msec, /** * Send the modifier state to focused keyboard resources. This function does * not respect keyboard grabs: you probably want - * `wlr_seat_keyboard_notify_modifiers()` instead. + * wlr_seat_keyboard_notify_modifiers() instead. */ void wlr_seat_keyboard_send_modifiers(struct wlr_seat *seat, struct wlr_keyboard_modifiers *modifiers); @@ -503,7 +503,7 @@ void wlr_seat_keyboard_send_modifiers(struct wlr_seat *seat, * Send a keyboard enter event to the given surface and consider it to be the * focused surface for the keyboard. This will send a leave event to the last * surface that was entered. This function does not respect keyboard grabs: you - * probably want `wlr_seat_keyboard_notify_enter()` instead. + * probably want wlr_seat_keyboard_notify_enter() instead. */ void wlr_seat_keyboard_enter(struct wlr_seat *seat, struct wlr_surface *surface, uint32_t keycodes[], size_t num_keycodes, @@ -512,7 +512,7 @@ void wlr_seat_keyboard_enter(struct wlr_seat *seat, /** * Clear the focused surface for the keyboard and leave all entered surfaces. * This function does not respect keyboard grabs: you probably want - * `wlr_seat_keyboard_notify_clear_focus()` instead. + * wlr_seat_keyboard_notify_clear_focus() instead. */ void wlr_seat_keyboard_clear_focus(struct wlr_seat *wlr_seat); @@ -573,7 +573,7 @@ struct wlr_touch_point *wlr_seat_touch_get_point(struct wlr_seat *seat, /** * Notify the seat that the touch point given by `touch_id` has entered a new * surface. The surface is required. To clear focus, use - * `wlr_seat_touch_point_clear_focus()`. + * wlr_seat_touch_point_clear_focus(). */ void wlr_seat_touch_point_focus(struct wlr_seat *seat, struct wlr_surface *surface, uint32_t time_msec, @@ -591,7 +591,7 @@ void wlr_seat_touch_point_clear_focus(struct wlr_seat *seat, uint32_t time_msec, * this will add a new touch point with the given `touch_id`. The touch down may * not be valid if the surface seat client does not accept touch input. * Coordinates are surface-local. This function does not respect touch grabs: - * you probably want `wlr_seat_touch_notify_down()` instead. + * you probably want wlr_seat_touch_notify_down() instead. */ uint32_t wlr_seat_touch_send_down(struct wlr_seat *seat, struct wlr_surface *surface, uint32_t time_msec, @@ -601,7 +601,7 @@ uint32_t wlr_seat_touch_send_down(struct wlr_seat *seat, * Send a touch up event for the touch point given by the `touch_id`. The event * will go to the client for the surface given in the corresponding touch down * event. This will remove the touch point. This function does not respect touch - * grabs: you probably want `wlr_seat_touch_notify_up()` instead. + * grabs: you probably want wlr_seat_touch_notify_up() instead. */ void wlr_seat_touch_send_up(struct wlr_seat *seat, uint32_t time_msec, int32_t touch_id); @@ -610,7 +610,7 @@ void wlr_seat_touch_send_up(struct wlr_seat *seat, uint32_t time_msec, * Send a touch motion event for the touch point given by the `touch_id`. The * event will go to the client for the surface given in the corresponding touch * down event. This function does not respect touch grabs: you probably want - * `wlr_seat_touch_notify_motion()` instead. + * wlr_seat_touch_notify_motion() instead. */ void wlr_seat_touch_send_motion(struct wlr_seat *seat, uint32_t time_msec, int32_t touch_id, double sx, double sy); @@ -619,7 +619,7 @@ void wlr_seat_touch_send_motion(struct wlr_seat *seat, uint32_t time_msec, * Notify the seat that this is a global gesture and the client should cancel * processing it. The event will go to the client for the surface given. * This function does not respect touch grabs: you probably want - * `wlr_seat_touch_notify_cancel()` instead. + * wlr_seat_touch_notify_cancel() instead. */ void wlr_seat_touch_send_cancel(struct wlr_seat *seat, struct wlr_surface *surface); @@ -695,7 +695,7 @@ bool wlr_seat_validate_pointer_grab_serial(struct wlr_seat *seat, /** * Check whether this serial is valid to start a touch grab action. If it's the - * case and point_ptr is non-NULL, *point_ptr is set to the touch point matching + * case and point_ptr is non-NULL, `*point_ptr` is set to the touch point matching * the serial. */ bool wlr_seat_validate_touch_grab_serial(struct wlr_seat *seat, diff --git a/include/wlr/types/wlr_server_decoration.h b/include/wlr/types/wlr_server_decoration.h index 28467a21..7e78c5f2 100644 --- a/include/wlr/types/wlr_server_decoration.h +++ b/include/wlr/types/wlr_server_decoration.h @@ -44,8 +44,8 @@ enum wlr_server_decoration_manager_mode { */ struct wlr_server_decoration_manager { struct wl_global *global; - struct wl_list resources; // wl_resource_get_link - struct wl_list decorations; // wlr_server_decoration::link + struct wl_list resources; // wl_resource_get_link() + struct wl_list decorations; // wlr_server_decoration.link uint32_t default_mode; // enum wlr_server_decoration_manager_mode diff --git a/include/wlr/types/wlr_session_lock_v1.h b/include/wlr/types/wlr_session_lock_v1.h index b410b9e5..101fe56c 100644 --- a/include/wlr/types/wlr_session_lock_v1.h +++ b/include/wlr/types/wlr_session_lock_v1.h @@ -31,7 +31,7 @@ struct wlr_session_lock_manager_v1 { struct wlr_session_lock_v1 { struct wl_resource *resource; - struct wl_list surfaces; // struct wlr_session_lock_surface_v1::link + struct wl_list surfaces; // struct wlr_session_lock_surface_v1.link struct { struct wl_signal new_surface; // struct wlr_session_lock_surface_v1 * @@ -48,7 +48,7 @@ struct wlr_session_lock_surface_v1_state { }; struct wlr_session_lock_surface_v1_configure { - struct wl_list link; // wlr_session_lock_surface_v1::configure_list + struct wl_list link; // wlr_session_lock_surface_v1.configure_list uint32_t serial; uint32_t width, height; @@ -56,14 +56,14 @@ struct wlr_session_lock_surface_v1_configure { struct wlr_session_lock_surface_v1 { struct wl_resource *resource; - struct wl_list link; // wlr_session_lock_v1::surfaces + struct wl_list link; // wlr_session_lock_v1.surfaces struct wlr_output *output; struct wlr_surface *surface; bool configured, mapped; - struct wl_list configure_list; // wlr_session_lock_surface_v1_configure::link + struct wl_list configure_list; // wlr_session_lock_surface_v1_configure.link struct wlr_session_lock_surface_v1_state current; struct wlr_session_lock_surface_v1_state pending; diff --git a/include/wlr/types/wlr_tablet_pad.h b/include/wlr/types/wlr_tablet_pad.h index 64420f46..32a3231d 100644 --- a/include/wlr/types/wlr_tablet_pad.h +++ b/include/wlr/types/wlr_tablet_pad.h @@ -30,14 +30,14 @@ struct wlr_tablet_pad { struct wl_signal button; struct wl_signal ring; struct wl_signal strip; - struct wl_signal attach_tablet; //struct wlr_tablet_tool + struct wl_signal attach_tablet; // struct wlr_tablet_tool } events; size_t button_count; size_t ring_count; size_t strip_count; - struct wl_list groups; // wlr_tablet_pad_group::link + struct wl_list groups; // wlr_tablet_pad_group.link struct wl_array paths; // char * void *data; diff --git a/include/wlr/types/wlr_tablet_v2.h b/include/wlr/types/wlr_tablet_v2.h index c05015b2..54828244 100644 --- a/include/wlr/types/wlr_tablet_v2.h +++ b/include/wlr/types/wlr_tablet_v2.h @@ -41,8 +41,8 @@ struct wlr_tablet_pad_client_v2; struct wlr_tablet_manager_v2 { struct wl_global *wl_global; - struct wl_list clients; // wlr_tablet_manager_client_v2::link - struct wl_list seats; // wlr_tablet_seat_v2::link + struct wl_list clients; // wlr_tablet_manager_client_v2.link + struct wl_list seats; // wlr_tablet_seat_v2.link struct wl_listener display_destroy; @@ -54,10 +54,10 @@ struct wlr_tablet_manager_v2 { }; struct wlr_tablet_v2_tablet { - struct wl_list link; // wlr_tablet_seat_v2::tablets + struct wl_list link; // wlr_tablet_seat_v2.tablets struct wlr_tablet *wlr_tablet; struct wlr_input_device *wlr_device; - struct wl_list clients; // wlr_tablet_client_v2::tablet_link + struct wl_list clients; // wlr_tablet_client_v2.tablet_link struct wl_listener tool_destroy; @@ -65,9 +65,9 @@ struct wlr_tablet_v2_tablet { }; struct wlr_tablet_v2_tablet_tool { - struct wl_list link; // wlr_tablet_seat_v2::tablets + struct wl_list link; // wlr_tablet_seat_v2.tablets struct wlr_tablet_tool *wlr_tool; - struct wl_list clients; // wlr_tablet_tool_client_v2::tool_link + struct wl_list clients; // wlr_tablet_tool_client_v2.tool_link struct wl_listener tool_destroy; @@ -91,10 +91,10 @@ struct wlr_tablet_v2_tablet_tool { }; struct wlr_tablet_v2_tablet_pad { - struct wl_list link; // wlr_tablet_seat_v2::pads + struct wl_list link; // wlr_tablet_seat_v2.pads struct wlr_tablet_pad *wlr_pad; struct wlr_input_device *wlr_device; - struct wl_list clients; // wlr_tablet_pad_client_v2::pad_link + struct wl_list clients; // wlr_tablet_pad_client_v2.pad_link size_t group_count; uint32_t *groups; diff --git a/include/wlr/types/wlr_text_input_v3.h b/include/wlr/types/wlr_text_input_v3.h index 5bac69a6..a3c6c7eb 100644 --- a/include/wlr/types/wlr_text_input_v3.h +++ b/include/wlr/types/wlr_text_input_v3.h @@ -39,7 +39,7 @@ struct wlr_text_input_v3_state { // Tracks which features were used in the current commit. // Useful in the enabling commit, where usage means support. - uint32_t features; // OR'ed wlr_text_input_v3_features + uint32_t features; // bitfield of enum wlr_text_input_v3_features }; struct wlr_text_input_v3 { @@ -52,7 +52,7 @@ struct wlr_text_input_v3 { bool pending_enabled; bool current_enabled; // supported in the current text input, more granular than surface - uint32_t active_features; // OR'ed wlr_text_input_v3_features + uint32_t active_features; // bitfield of enum wlr_text_input_v3_features struct wl_list link; @@ -60,22 +60,22 @@ struct wlr_text_input_v3 { struct wl_listener seat_destroy; struct { - struct wl_signal enable; // (struct wlr_text_input_v3*) - struct wl_signal commit; // (struct wlr_text_input_v3*) - struct wl_signal disable; // (struct wlr_text_input_v3*) - struct wl_signal destroy; // (struct wlr_text_input_v3*) + struct wl_signal enable; // struct wlr_text_input_v3 * + struct wl_signal commit; // struct wlr_text_input_v3 * + struct wl_signal disable; // struct wlr_text_input_v3 * + struct wl_signal destroy; // struct wlr_text_input_v3 * } events; }; struct wlr_text_input_manager_v3 { struct wl_global *global; - struct wl_list text_inputs; // struct wlr_text_input_v3::resource::link + struct wl_list text_inputs; // struct wlr_text_input_v3.resource.link struct wl_listener display_destroy; struct { - struct wl_signal text_input; // (struct wlr_text_input_v3*) - struct wl_signal destroy; // (struct wlr_input_method_manager_v3*) + struct wl_signal text_input; // struct wlr_text_input_v3 * + struct wl_signal destroy; // struct wlr_input_method_manager_v3 * } events; }; diff --git a/include/wlr/types/wlr_viewporter.h b/include/wlr/types/wlr_viewporter.h index f909d9cc..8a179367 100644 --- a/include/wlr/types/wlr_viewporter.h +++ b/include/wlr/types/wlr_viewporter.h @@ -18,9 +18,9 @@ * * - The size of the surface texture may not match the surface size anymore. * Compositors must use the surface size only. - * - Compositors must call wlr_render_subtexture_with_matrix when rendering a + * - Compositors must call wlr_render_subtexture_with_matrix() when rendering a * surface texture with the source box returned by - * wlr_surface_get_buffer_source_box. + * wlr_surface_get_buffer_source_box(). */ struct wlr_viewporter { struct wl_global *global; diff --git a/include/wlr/types/wlr_virtual_keyboard_v1.h b/include/wlr/types/wlr_virtual_keyboard_v1.h index 8350f413..00200c44 100644 --- a/include/wlr/types/wlr_virtual_keyboard_v1.h +++ b/include/wlr/types/wlr_virtual_keyboard_v1.h @@ -14,12 +14,12 @@ struct wlr_virtual_keyboard_manager_v1 { struct wl_global *global; - struct wl_list virtual_keyboards; // struct wlr_virtual_keyboard_v1* + struct wl_list virtual_keyboards; // wlr_virtual_keyboard_v1.link struct wl_listener display_destroy; struct { - struct wl_signal new_virtual_keyboard; // struct wlr_virtual_keyboard_v1* + struct wl_signal new_virtual_keyboard; // struct wlr_virtual_keyboard_v1 * struct wl_signal destroy; } events; }; @@ -30,7 +30,7 @@ struct wlr_virtual_keyboard_v1 { struct wlr_seat *seat; bool has_keymap; - struct wl_list link; + struct wl_list link; // wlr_virtual_keyboard_manager_v1.virtual_keyboards }; struct wlr_virtual_keyboard_manager_v1* wlr_virtual_keyboard_manager_v1_create( diff --git a/include/wlr/types/wlr_virtual_pointer_v1.h b/include/wlr/types/wlr_virtual_pointer_v1.h index 954103e1..d00f2758 100644 --- a/include/wlr/types/wlr_virtual_pointer_v1.h +++ b/include/wlr/types/wlr_virtual_pointer_v1.h @@ -16,12 +16,12 @@ struct wlr_virtual_pointer_manager_v1 { struct wl_global *global; - struct wl_list virtual_pointers; // struct wlr_virtual_pointer_v1* + struct wl_list virtual_pointers; // wlr_virtual_pointer_v1.link struct wl_listener display_destroy; struct { - struct wl_signal new_virtual_pointer; // struct wlr_virtual_pointer_v1_new_pointer_event* + struct wl_signal new_virtual_pointer; // struct wlr_virtual_pointer_v1_new_pointer_event * struct wl_signal destroy; } events; }; @@ -34,7 +34,7 @@ struct wlr_virtual_pointer_v1 { enum wl_pointer_axis axis; bool axis_valid[2]; - struct wl_list link; + struct wl_list link; // wlr_virtual_pointer_manager_v1.virtual_pointers }; struct wlr_virtual_pointer_v1_new_pointer_event { diff --git a/include/wlr/types/wlr_xcursor_manager.h b/include/wlr/types/wlr_xcursor_manager.h index a9530214..f7781ca6 100644 --- a/include/wlr/types/wlr_xcursor_manager.h +++ b/include/wlr/types/wlr_xcursor_manager.h @@ -23,9 +23,9 @@ struct wlr_xcursor_manager_theme { }; /** - * wlr_xcursor_manager dynamically loads xcursor themes at sizes necessary for - * use on outputs at arbitrary scale factors. You should call - * wlr_xcursor_manager_load for each output you will show your cursor on, with + * struct wlr_xcursor_manager dynamically loads xcursor themes at sizes necessary + * for use on outputs at arbitrary scale factors. You should call + * wlr_xcursor_manager_load() for each output you will show your cursor on, with * the scale factor parameter set to that output's scale factor. */ struct wlr_xcursor_manager { @@ -51,17 +51,17 @@ bool wlr_xcursor_manager_load(struct wlr_xcursor_manager *manager, /** * Retrieves a wlr_xcursor reference for the given cursor name at the given - * scale factor, or NULL if this wlr_xcursor_manager has not loaded a cursor - * theme at the requested scale. + * scale factor, or NULL if this struct wlr_xcursor_manager has not loaded a + * cursor theme at the requested scale. */ struct wlr_xcursor *wlr_xcursor_manager_get_xcursor( struct wlr_xcursor_manager *manager, const char *name, float scale); /** - * Set a wlr_cursor's cursor image to the specified cursor name for all scale - * factors. wlr_cursor will take over from this point and ensure the correct - * cursor is used on each output, assuming a wlr_output_layout is attached to - * it. + * Set a struct wlr_cursor's cursor image to the specified cursor name for all + * scale factors. struct wlr_cursor will take over from this point and ensure + * the correct cursor is used on each output, assuming a + * struct wlr_output_layout is attached to it. */ void wlr_xcursor_manager_set_cursor_image(struct wlr_xcursor_manager *manager, const char *name, struct wlr_cursor *cursor); diff --git a/include/wlr/types/wlr_xdg_activation_v1.h b/include/wlr/types/wlr_xdg_activation_v1.h index 97801af2..f36be464 100644 --- a/include/wlr/types/wlr_xdg_activation_v1.h +++ b/include/wlr/types/wlr_xdg_activation_v1.h @@ -45,7 +45,7 @@ struct wlr_xdg_activation_v1 { struct { struct wl_signal destroy; - struct wl_signal request_activate; // wlr_xdg_activation_v1_request_activate_event + struct wl_signal request_activate; // struct wlr_xdg_activation_v1_request_activate_event } events; // private state diff --git a/include/wlr/types/wlr_xdg_decoration_v1.h b/include/wlr/types/wlr_xdg_decoration_v1.h index b3651559..138eb020 100644 --- a/include/wlr/types/wlr_xdg_decoration_v1.h +++ b/include/wlr/types/wlr_xdg_decoration_v1.h @@ -12,7 +12,7 @@ enum wlr_xdg_toplevel_decoration_v1_mode { struct wlr_xdg_decoration_manager_v1 { struct wl_global *global; - struct wl_list decorations; // wlr_xdg_toplevel_decoration::link + struct wl_list decorations; // wlr_xdg_toplevel_decoration.link struct wl_listener display_destroy; @@ -25,7 +25,7 @@ struct wlr_xdg_decoration_manager_v1 { }; struct wlr_xdg_toplevel_decoration_v1_configure { - struct wl_list link; // wlr_xdg_toplevel_decoration::configure_list + struct wl_list link; // wlr_xdg_toplevel_decoration.configure_list struct wlr_xdg_surface_configure *surface_configure; enum wlr_xdg_toplevel_decoration_v1_mode mode; }; @@ -38,7 +38,7 @@ struct wlr_xdg_toplevel_decoration_v1 { struct wl_resource *resource; struct wlr_xdg_surface *surface; struct wlr_xdg_decoration_manager_v1 *manager; - struct wl_list link; // wlr_xdg_decoration_manager_v1::link + struct wl_list link; // wlr_xdg_decoration_manager_v1.link struct wlr_xdg_toplevel_decoration_v1_state current, pending; @@ -47,7 +47,7 @@ struct wlr_xdg_toplevel_decoration_v1 { bool added; - struct wl_list configure_list; // wlr_xdg_toplevel_decoration_v1_configure::link + struct wl_list configure_list; // wlr_xdg_toplevel_decoration_v1_configure.link struct { struct wl_signal destroy; diff --git a/include/wlr/types/wlr_xdg_foreign_registry.h b/include/wlr/types/wlr_xdg_foreign_registry.h index 462a9a86..54c91e4d 100644 --- a/include/wlr/types/wlr_xdg_foreign_registry.h +++ b/include/wlr/types/wlr_xdg_foreign_registry.h @@ -14,8 +14,8 @@ #define WLR_XDG_FOREIGN_HANDLE_SIZE 37 /** - * wlr_xdg_foreign_registry is used for storing a list of exported surfaces with - * the xdg-foreign family of protocols. + * struct wlr_xdg_foreign_registry is used for storing a list of exported + * surfaces with the xdg-foreign family of protocols. * * It can be used to allow interoperability between clients using different * versions of the protocol (if all versions use the same registry). @@ -30,7 +30,7 @@ struct wlr_xdg_foreign_registry { }; struct wlr_xdg_foreign_exported { - struct wl_list link; // wlr_xdg_foreign_registry::exported_surfaces + struct wl_list link; // wlr_xdg_foreign_registry.exported_surfaces struct wlr_xdg_foreign_registry *registry; struct wlr_surface *surface; @@ -43,7 +43,7 @@ struct wlr_xdg_foreign_exported { }; /** - * Create an empty wlr_xdg_foreign_registry. + * Create an empty struct wlr_xdg_foreign_registry. * * It will be destroyed when the associated display is destroyed. */ diff --git a/include/wlr/types/wlr_xdg_foreign_v1.h b/include/wlr/types/wlr_xdg_foreign_v1.h index bebbb8ae..25bc1181 100644 --- a/include/wlr/types/wlr_xdg_foreign_v1.h +++ b/include/wlr/types/wlr_xdg_foreign_v1.h @@ -15,7 +15,7 @@ struct wlr_xdg_foreign_v1 { struct { struct wl_global *global; - struct wl_list objects; // wlr_xdg_exported_v1::link or wlr_xdg_imported_v1::link + struct wl_list objects; // wlr_xdg_exported_v1.link or wlr_xdg_imported_v1.link } exporter, importer; struct wl_listener foreign_registry_destroy; @@ -36,7 +36,7 @@ struct wlr_xdg_exported_v1 { struct wl_resource *resource; struct wl_listener xdg_surface_unmap; - struct wl_list link; // wlr_xdg_foreign_v1::exporter::objects + struct wl_list link; // wlr_xdg_foreign_v1.exporter.objects }; struct wlr_xdg_imported_v1 { @@ -44,7 +44,7 @@ struct wlr_xdg_imported_v1 { struct wl_listener exported_destroyed; struct wl_resource *resource; - struct wl_list link; // wlr_xdg_foreign_v1::importer::objects + struct wl_list link; // wlr_xdg_foreign_v1.importer.objects struct wl_list children; }; @@ -52,7 +52,7 @@ struct wlr_xdg_imported_child_v1 { struct wlr_xdg_imported_v1 *imported; struct wlr_surface *surface; - struct wl_list link; // wlr_xdg_imported_v1::children + struct wl_list link; // wlr_xdg_imported_v1.children struct wl_listener xdg_surface_unmap; struct wl_listener xdg_toplevel_set_parent; diff --git a/include/wlr/types/wlr_xdg_foreign_v2.h b/include/wlr/types/wlr_xdg_foreign_v2.h index 23c8247b..78659e97 100644 --- a/include/wlr/types/wlr_xdg_foreign_v2.h +++ b/include/wlr/types/wlr_xdg_foreign_v2.h @@ -15,7 +15,7 @@ struct wlr_xdg_foreign_v2 { struct { struct wl_global *global; - struct wl_list objects; // wlr_xdg_exported_v2::link or wlr_xdg_imported_v2::link + struct wl_list objects; // wlr_xdg_exported_v2.link or wlr_xdg_imported_v2.link } exporter, importer; struct wl_listener foreign_registry_destroy; @@ -36,7 +36,7 @@ struct wlr_xdg_exported_v2 { struct wl_resource *resource; struct wl_listener xdg_surface_unmap; - struct wl_list link; // wlr_xdg_foreign_v2::exporter::objects + struct wl_list link; // wlr_xdg_foreign_v2.exporter.objects }; struct wlr_xdg_imported_v2 { @@ -44,7 +44,7 @@ struct wlr_xdg_imported_v2 { struct wl_listener exported_destroyed; struct wl_resource *resource; - struct wl_list link; // wlr_xdg_foreign_v2::importer::objects + struct wl_list link; // wlr_xdg_foreign_v2.importer.objects struct wl_list children; }; @@ -52,7 +52,7 @@ struct wlr_xdg_imported_child_v2 { struct wlr_xdg_imported_v2 *imported; struct wlr_surface *surface; - struct wl_list link; // wlr_xdg_imported_v2::children + struct wl_list link; // wlr_xdg_imported_v2.children struct wl_listener xdg_surface_unmap; struct wl_listener xdg_toplevel_set_parent; diff --git a/include/wlr/types/wlr_xdg_shell.h b/include/wlr/types/wlr_xdg_shell.h index e6168317..51ba0584 100644 --- a/include/wlr/types/wlr_xdg_shell.h +++ b/include/wlr/types/wlr_xdg_shell.h @@ -44,7 +44,7 @@ struct wlr_xdg_client { struct wl_client *client; struct wl_list surfaces; - struct wl_list link; // wlr_xdg_shell::clients + struct wl_list link; // wlr_xdg_shell.clients uint32_t ping_serial; struct wl_event_source *ping_timer; @@ -85,7 +85,7 @@ struct wlr_xdg_popup { struct wlr_xdg_positioner_rules positioner_rules; - struct wl_list grab_link; // wlr_xdg_popup_grab::popups + struct wl_list grab_link; // wlr_xdg_popup_grab.popups }; // each seat gets a popup grab @@ -96,7 +96,7 @@ struct wlr_xdg_popup_grab { struct wlr_seat_touch_grab touch_grab; struct wlr_seat *seat; struct wl_list popups; - struct wl_list link; // wlr_xdg_shell::popup_grabs + struct wl_list link; // wlr_xdg_shell.popup_grabs struct wl_listener seat_destroy; }; @@ -141,7 +141,7 @@ struct wlr_xdg_toplevel { // Properties that the client has requested. Intended to be checked // by the compositor on surface map and state change requests (such as - // xdg_toplevel::set_fullscreen) and handled accordingly. + // xdg_toplevel.set_fullscreen) and handled accordingly. struct wlr_xdg_toplevel_requested requested; char *title; @@ -170,7 +170,7 @@ struct wlr_xdg_toplevel { struct wlr_xdg_surface_configure { struct wlr_xdg_surface *surface; - struct wl_list link; // wlr_xdg_surface::configure_list + struct wl_list link; // wlr_xdg_surface.configure_list uint32_t serial; struct wlr_xdg_toplevel_configure *toplevel_configure; @@ -195,7 +195,7 @@ struct wlr_xdg_surface { struct wlr_xdg_client *client; struct wl_resource *resource; struct wlr_surface *surface; - struct wl_list link; // wlr_xdg_client::surfaces + struct wl_list link; // wlr_xdg_client.surfaces enum wlr_xdg_surface_role role; union { @@ -203,7 +203,7 @@ struct wlr_xdg_surface { struct wlr_xdg_popup *popup; }; - struct wl_list popups; // wlr_xdg_popup::link + struct wl_list popups; // wlr_xdg_popup.link bool added, configured, mapped; struct wl_event_source *configure_idle; @@ -237,8 +237,8 @@ struct wlr_xdg_surface { struct wl_signal unmap; // for protocol extensions - struct wl_signal configure; // wlr_xdg_surface_configure - struct wl_signal ack_configure; // wlr_xdg_surface_configure + struct wl_signal configure; // struct wlr_xdg_surface_configure + struct wl_signal ack_configure; // struct wlr_xdg_surface_configure } events; void *data; @@ -270,7 +270,7 @@ struct wlr_xdg_toplevel_show_window_menu_event { struct wlr_xdg_shell *wlr_xdg_shell_create(struct wl_display *display, uint32_t version); -/** Get the corresponding wlr_xdg_surface from a resource. +/** Get the corresponding struct wlr_xdg_surface from a resource. * * Aborts if the resource doesn't have the correct type. Returns NULL if the * resource is inert. @@ -278,7 +278,7 @@ struct wlr_xdg_shell *wlr_xdg_shell_create(struct wl_display *display, struct wlr_xdg_surface *wlr_xdg_surface_from_resource( struct wl_resource *resource); -/** Get the corresponding wlr_xdg_popup from a resource. +/** Get the corresponding struct wlr_xdg_popup from a resource. * * Aborts if the resource doesn't have the correct type. Returns NULL if the * resource is inert. @@ -286,7 +286,7 @@ struct wlr_xdg_surface *wlr_xdg_surface_from_resource( struct wlr_xdg_popup *wlr_xdg_popup_from_resource( struct wl_resource *resource); -/** Get the corresponding wlr_xdg_toplevel from a resource. +/** Get the corresponding struct wlr_xdg_toplevel from a resource. * * Aborts if the resource doesn't have the correct type. Returns NULL if the * resource is inert. @@ -294,7 +294,7 @@ struct wlr_xdg_popup *wlr_xdg_popup_from_resource( struct wlr_xdg_toplevel *wlr_xdg_toplevel_from_resource( struct wl_resource *resource); -/** Get the corresponding wlr_xdg_positioner from a resource. +/** Get the corresponding struct wlr_xdg_positioner from a resource. * * Aborts if the resource doesn't have the correct type. */ @@ -345,7 +345,7 @@ uint32_t wlr_xdg_toplevel_set_resizing(struct wlr_xdg_toplevel *toplevel, /** * Request that this toplevel consider itself in a tiled layout and some * edges are adjacent to another part of the tiling grid. `tiled_edges` is a - * bitfield of `enum wlr_edges`. Returns the associated configure serial. + * bitfield of enum wlr_edges. Returns the associated configure serial. */ uint32_t wlr_xdg_toplevel_set_tiled(struct wlr_xdg_toplevel *toplevel, uint32_t tiled_edges); @@ -425,10 +425,11 @@ struct wlr_xdg_surface *wlr_xdg_surface_from_wlr_surface( /** * Get the surface geometry. + * * This is either the geometry as set by the client, or defaulted to the bounds * of the surface + the subsurfaces (as specified by the protocol). * - * The x and y value can be <0 + * The x and y value can be < 0. */ void wlr_xdg_surface_get_geometry(struct wlr_xdg_surface *surface, struct wlr_box *box); diff --git a/include/wlr/util/box.h b/include/wlr/util/box.h index 66cfa21c..8516688d 100644 --- a/include/wlr/util/box.h +++ b/include/wlr/util/box.h @@ -23,7 +23,7 @@ * * The x and y coordinates are inclusive, and the width and height lengths are * exclusive. In other words, the box starts from the coordinates (x, y), and - * goes up to but not including (x + width, y + height) + * goes up to but not including (x + width, y + height). */ struct wlr_box { int x, y; @@ -33,7 +33,7 @@ struct wlr_box { /** * A floating-point box representing a rectangle region in a 2D space. * - * wlr_fbox has the same semantics as wlr_box + * struct wlr_fbox has the same semantics as struct wlr_box. */ struct wlr_fbox { double x, y; @@ -41,34 +41,35 @@ struct wlr_fbox { }; /** - * Finds the closest point within the box bounds + * Finds the closest point within the box bounds. * - * Returns NAN if the box is empty + * Returns NAN if the box is empty. */ void wlr_box_closest_point(const struct wlr_box *box, double x, double y, double *dest_x, double *dest_y); /** - * Gives the intersecting box between two wlr_box. + * Gives the intersecting box between two struct wlr_box. * - * Returns an empty wlr_box if the provided wlr_box don't intersect. + * Returns an empty box if the provided boxes don't intersect. */ bool wlr_box_intersection(struct wlr_box *dest, const struct wlr_box *box_a, const struct wlr_box *box_b); /** - * Verifies if a point is contained within the bounds of a given wlr_box. + * Verifies if a point is contained within the bounds of a given struct wlr_box. * * For example: - * - A point at (100, 50) is not contained in the box (0, 0, 100, 50). - * - A point at (10, 10) is contained in the box (10, 0, 50, 50). + * + * - A point at (100, 50) is not contained in the box (0, 0, 100, 50). + * - A point at (10, 10) is contained in the box (10, 0, 50, 50). */ bool wlr_box_contains_point(const struct wlr_box *box, double x, double y); /** * Checks whether a box is empty or not. * - * A wlr_box is considered empty if its width and/or height is zero or negative. + * A box is considered empty if its width and/or height is zero or negative. */ bool wlr_box_empty(const struct wlr_box *box); @@ -81,7 +82,7 @@ void wlr_box_transform(struct wlr_box *dest, const struct wlr_box *box, /** * Checks whether a box is empty or not. * - * A wlr_box is considered empty if its width and/or height is zero or negative. + * A box is considered empty if its width and/or height is zero or negative. */ bool wlr_fbox_empty(const struct wlr_fbox *box); diff --git a/include/wlr/util/log.h b/include/wlr/util/log.h index aacdea99..5e5d8393 100644 --- a/include/wlr/util/log.h +++ b/include/wlr/util/log.h @@ -32,13 +32,20 @@ enum wlr_log_importance { typedef void (*wlr_log_func_t)(enum wlr_log_importance importance, const char *fmt, va_list args); -// Will log all messages less than or equal to `verbosity` -// If `callback` is NULL, wlr will use its default logger. -// The function can be called multiple times to update the verbosity or -// callback function. +/** + * Set the log verbosity and callback. + * + * Only messages less than or equal to the supplied verbosity will be logged. + * If the callback is NULL, the default logger is used. + * + * This function can be called multiple times to update the verbosity or + * callback function. + */ void wlr_log_init(enum wlr_log_importance verbosity, wlr_log_func_t callback); -// Returns the log verbosity provided to wlr_log_init +/** + * Get the current log verbosity configured by wlr_log_init(). + */ enum wlr_log_importance wlr_log_get_verbosity(void); #ifdef __GNUC__ |