Reformat doc comments

Unify the way we document our APIs. See CONTRIBUTING.md for the
rules.

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);

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,

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
+ * Create a new headless output.
- * read pixels from this framebuffer via wlr_renderer_read_pixels but it is
+ *
- * otherwise not displayed.
+ * 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);

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
+ * Initializes common state on a struct wlr_backend and sets the implementation
- * provided wlr_backend_impl reference.
+ * to the provided struct wlr_backend_impl reference.
  */
 void wlr_backend_init(struct wlr_backend *backend,
 		const struct wlr_backend_impl *impl);

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);
 

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
+ * You should call wlr_session_close_file() on each files you opened
- * with wlr_session_open_file before you call this.
+ * 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);

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;
+ * Creates a new Wayland backend. This backend will be created with no outputs;
- * you must use wlr_wl_output_create to add them.
+ * 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);
 

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;
+ * Creates a new X11 backend. This backend will be created with no outputs;
- * you must use wlr_x11_output_create to add them.
+ * 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);
 

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
+ * The matching function will be called for the struct wl_resource when creating
- * wlr_buffer from a wl_resource.
+ * a struct wlr_buffer from a struct wl_resource.
  */
 void wlr_buffer_register_resource_interface(
 	const struct wlr_buffer_resource_interface *iface);

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);
 

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);

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.
+ * Cleans up the resources owned by a struct 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.
+ * 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);
 

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

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(

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);
 

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);
 

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);
 

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
+ * These bits indicate the features supported by a struct wlr_buffer. There is
- * per function in wlr_buffer_impl.
+ * 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
+ * struct wlr_buffer. The caller isn't responsible for cleaning up the shared
- * attributes.
+ * 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
+ * Transforms a struct wl_resource into a struct wlr_buffer and locks it. Once
- * done with the buffer, they must call wlr_buffer_unlock.
+ * 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
+ * Creates a struct wlr_client_buffer from a given struct wlr_buffer by creating
- * from it, and copying its wl_resource.
+ * 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);

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
+ * Get the struct wlr_surface corresponding to a wl_surface resource.
- * that the resource is a valid wl_surface resource created by wlroots and
+ *
- * will never return NULL.
+ * 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.

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,
+ * this in global coordinates, and integrates with struct wlr_output,
- * wlr_output_layout, and wlr_input_device. You can use it to abstract multiple
+ * struct wlr_output_layout, and struct wlr_input_device. You can use it to
- * input devices over a single cursor, constrain cursor movement to the usable
+ * abstract multiple input devices over a single cursor, constrain cursor
- * area of a wlr_output_layout and communicate position updates to the hardware
+ * movement to the usable area of a struct wlr_output_layout and communicate
- * cursor, constrain specific input devices to specific outputs or regions of
+ * position updates to the hardware cursor, constrain specific input devices to
- * the screen, and so on.
+ * 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_move(). If you receive an absolute event, call
-	 * wlr_cursor_warp_absolute. If you pass an input device into these
+	 * 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
+	 * Re-broadcasting these signals to, for example, a struct wlr_seat, is also
-	 * responsibility.
+	 * 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);

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

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 motion; // struct wlr_drag_motion_event
-		struct wl_signal drop; // wlr_drag_drop_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,

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 connectors; // wlr_drm_lease_connector_v1.link
-	struct wl_list leases; // wlr_drm_lease_v1::link
+	struct wl_list leases; // wlr_drm_lease_v1.link
-	struct wl_list requests; // wlr_drm_lease_request_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 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;

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;
 

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 resources; // wl_resource_get_link()
-	struct wl_list toplevels; // wlr_foreign_toplevel_handle_v1::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
+	struct wl_list outputs; // wlr_foreign_toplevel_v1_output.link
-	uint32_t state; // wlr_foreign_toplevel_v1_state
+	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);

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;
 

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;
 

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;
 

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;

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 commit; // struct wlr_input_method_v2 *
-		struct wl_signal new_popup_surface; // (struct wlr_input_popup_surface_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 grab_keyboard; // struct wlr_input_method_keyboard_grab_v2 *
-		struct wl_signal destroy; // (struct wlr_input_method_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 input_method; // struct wlr_input_method_v2 *
-		struct wl_signal destroy; // (struct wlr_input_method_manager_v2*)
+		struct wl_signal destroy; // struct wlr_input_method_manager_v2 *
 	} events;
 };
 

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
+		 * The `key` event signals with a struct wlr_event_keyboard_key_event
-		 * key has been pressed or released on the keyboard. This event is
+		 * 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
+		 * struct wlr_keyboard has been updated. At this time, you can read the
-		 * modifier state of the `wlr_keyboard` and handle the updated state by
+		 * modifier state of the struct wlr_keyboard and handle the updated
-		 * sending it to clients.
+		 * state by sending it to clients.
 		 */
 		struct wl_signal modifiers;
 		struct wl_signal keymap;

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 devices; // keyboard_group_device.link
-	struct wl_list keys; // keyboard_group_key::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.
+		 * data for this signal will be a struct wl_array containing the key
-		 * This should be used to update the compositor's internal state.
+		 * 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
+		 * this signal will be a struct wl_array containing the key codes. This
-		 * be used to update the compositor's internal state. Bindings should
+		 * should be used to update the compositor's internal state. Bindings
-		 * not be triggered based off of these key codes. Additionally, surfaces
+		 * should not be triggered based off of these key codes. Additionally,
-		 * should only be notified if they received a corresponding key press
+		 * surfaces should only be notified if they received a corresponding key
-		 * for the key code.
+		 * press for the key code.
 		 */
 		struct wl_signal leave;
 	} events;

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 {

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
+		 * The destroy signal indicates that the struct wlr_layer_surface is
-		 * freed. It is guaranteed that the unmap signal is raised before the destroy
+		 * about to be freed. It is guaranteed that the unmap signal is raised
-		 * signal if the layer surface is destroyed while mapped.
+		 * 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.
  */

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
+ * Returns the struct wlr_dmabuf_buffer if the given resource was created
- * via the linux-dmabuf buffer protocol
+ * 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);

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`,
+ * To render a new frame, compositors should call wlr_output_attach_render(),
- * render and call `wlr_output_commit`. No rendering should happen outside a
+ * render and call wlr_output_commit(). No rendering should happen outside a
- * `frame` event handler or before `wlr_output_attach_render`.
+ * `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,
+ * Call this function prior to any call to wlr_output_attach_render(),
- * wlr_output_commit or wlr_output_cursor_create.
+ * 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);

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

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,

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 apply; // struct wlr_output_configuration_v1
-		struct wl_signal test; // 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 resources; // wl_resource_get_link()
-	struct wl_list mode_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
+ * status with wlr_output_configuration_head_v1_create(). They can then call
- * `wlr_output_manager_v1_set_configuration`.
+ * wlr_output_manager_v1_set_configuration().
  */
 struct wlr_output_configuration_v1 *wlr_output_configuration_v1_create(void);
 void wlr_output_configuration_v1_destroy(

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;

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;

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 swipes; // wl_resource_get_link()
-	struct wl_list pinches; // wl_resource_get_link
+	struct wl_list pinches; // wl_resource_get_link()
-	struct wl_list holds; // wl_resource_get_link
+	struct wl_list holds; // wl_resource_get_link()
 
 	struct wl_listener display_destroy;
 

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
+	// Only when the wlr_presentation_surface_sampled_on_output() helper has
-	// called
+	// 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,
+ * wlr_presentation_feedback_send_presented() if this content has been displayed,
- * then wlr_presentation_feedback_destroy.
+ * 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
+ * Instead of calling wlr_presentation_surface_sampled() and managing the
- * wlr_presentation_feedback itself, the compositor can call this function
+ * struct wlr_presentation_feedback itself, the compositor can call this function
- * before a wlr_output_commit call to indicate that the surface's current
+ * 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(

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 link; // wlr_primary_selection_v1_device_manager.devices
-	struct wl_list resources; // wl_resource_get_link
+	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;

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;

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.
  */

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;

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,

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 resources; // wl_resource_get_link()
-	struct wl_list decorations; // wlr_server_decoration::link
+	struct wl_list decorations; // wlr_server_decoration.link
 
 	uint32_t default_mode; // enum wlr_server_decoration_manager_mode
 

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;

include/wlr/types/wlr_tablet_pad.h

@@ -37,7 +37,7 @@ struct wlr_tablet_pad {
 	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;

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 clients; // wlr_tablet_manager_client_v2.link
-	struct wl_list seats; // wlr_tablet_seat_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;

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 enable; // struct wlr_text_input_v3 *
-		struct wl_signal commit; // (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 disable; // struct wlr_text_input_v3 *
-		struct wl_signal destroy; // (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 text_input; // struct wlr_text_input_v3 *
-		struct wl_signal destroy; // (struct wlr_input_method_manager_v3*)
+		struct wl_signal destroy; // struct wlr_input_method_manager_v3 *
 	} events;
 };
 

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;

include/wlr/types/wlr_virtual_keyboard_v1.h

@@ -14,7 +14,7 @@
 
 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;
 
@@ -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(

include/wlr/types/wlr_virtual_pointer_v1.h

@@ -16,7 +16,7 @@
 
 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;
 
@@ -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 {

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
+ * struct wlr_xcursor_manager dynamically loads xcursor themes at sizes necessary
- * use on outputs at arbitrary scale factors. You should call
+ * 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
+ * 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
+ * scale factor, or NULL if this struct wlr_xcursor_manager has not loaded a
- * theme at the requested scale.
+ * 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
+ * Set a struct wlr_cursor's cursor image to the specified cursor name for all
- * factors. wlr_cursor will take over from this point and ensure the correct
+ * scale factors. struct wlr_cursor will take over from this point and ensure
- * cursor is used on each output, assuming a wlr_output_layout is attached to
+ * the correct cursor is used on each output, assuming a
- * it.
+ * 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);

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

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;

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
+ * struct wlr_xdg_foreign_registry is used for storing a list of exported
- * the xdg-foreign family of protocols.
+ * 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.
  */

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;

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;

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 configure; // struct wlr_xdg_surface_configure
-		struct wl_signal ack_configure; // 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);

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,25 +41,26 @@ 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).
  */
@@ -68,7 +69,7 @@ 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);
 

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.
+ * Set the log verbosity and callback.
-// The function can be called multiple times to update the verbosity or
+ *
-// callback function.
+ * 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__