Reformat doc comments

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

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
- * read pixels from this framebuffer via wlr_renderer_read_pixels but it is
- * otherwise not displayed.
+ * Create a new headless output.
+ *
+ * The buffers presented on the output won't be displayed to the user.
  */
 struct wlr_output *wlr_headless_add_output(struct wlr_backend *backend,
 	unsigned int width, unsigned int height);

include/wlr/backend/interface.h

@@ -23,8 +23,8 @@ struct wlr_backend_impl {
 };
 
 /**
- * Initializes common state on a wlr_backend and sets the implementation to the
- * provided wlr_backend_impl reference.
+ * Initializes common state on a struct wlr_backend and sets the implementation
+ * to the provided struct wlr_backend_impl reference.
  */
 void wlr_backend_init(struct wlr_backend *backend,
 		const struct wlr_backend_impl *impl);

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
- * with wlr_session_open_file before you call this.
+ * You should call wlr_session_close_file() on each files you opened
+ * with wlr_session_open_file() before you call this.
  */
 void wlr_session_destroy(struct wlr_session *session);
 
 /*
  * Opens the file at path.
- * This can only be used to open DRM or evdev (input) devices.
+ *
+ * This can only be used to open DRM or evdev (input) devices. Files opened via
+ * this function must be closed by calling wlr_session_close_file().
  *
  * When the session becomes inactive:
+ *
  * - DRM files lose their DRM master status
  * - evdev files become invalid and should be closed
- *
- * Returns -errno on error.
  */
 struct wlr_device *wlr_session_open_file(struct wlr_session *session,
 	const char *path);
 
 /*
- * Closes a file previously opened with wlr_session_open_file.
+ * Closes a file previously opened with wlr_session_open_file().
  */
 void wlr_session_close_file(struct wlr_session *session,
 	struct wlr_device *device);

include/wlr/backend/wayland.h

@@ -9,18 +9,18 @@
 struct wlr_input_device;
 
 /**
- * Creates a new wlr_wl_backend. This backend will be created with no outputs;
- * you must use wlr_wl_output_create to add them.
+ * Creates a new Wayland backend. This backend will be created with no outputs;
+ * you must use wlr_wl_output_create() to add them.
  *
  * The `remote` argument is the name of the host compositor wayland socket. Set
  * to NULL for the default behaviour (WAYLAND_DISPLAY env variable or wayland-0
- * default)
+ * default).
  */
 struct wlr_backend *wlr_wl_backend_create(struct wl_display *display,
 		const char *remote);
 
 /**
- * Returns the remote wl_display used by the Wayland backend.
+ * Returns the remote struct wl_display used by the Wayland backend.
  */
 struct wl_display *wlr_wl_backend_get_remote_display(struct wlr_backend *backend);
 
@@ -28,37 +28,37 @@ struct wl_display *wlr_wl_backend_get_remote_display(struct wlr_backend *backend
  * Adds a new output to this backend. You may remove outputs by destroying them.
  * Note that if called before initializing the backend, this will return NULL
  * and your outputs will be created during initialization (and given to you via
- * the output_add signal).
+ * the new_output signal).
  */
 struct wlr_output *wlr_wl_output_create(struct wlr_backend *backend);
 
 /**
- * True if the given backend is a wlr_wl_backend.
+ * Check whether the provided backend is a Wayland backend.
  */
 bool wlr_backend_is_wl(struct wlr_backend *backend);
 
 /**
- * True if the given input device is a wlr_wl_input_device.
+ * Check whether the provided input device is a Wayland input device.
  */
 bool wlr_input_device_is_wl(struct wlr_input_device *device);
 
 /**
- * True if the given output is a wlr_wl_output.
+ * Check whether the provided output device is a Wayland output device.
  */
 bool wlr_output_is_wl(struct wlr_output *output);
 
 /**
- * Sets the title of a wlr_output which is a Wayland window.
+ * Sets the title of a struct wlr_output which is a Wayland toplevel.
  */
 void wlr_wl_output_set_title(struct wlr_output *output, const char *title);
 
 /**
- * Returns the remote wl_surface used by the Wayland output.
+ * Returns the remote struct wl_surface used by the Wayland output.
  */
 struct wl_surface *wlr_wl_output_get_surface(struct wlr_output *output);
 
 /**
- * Returns the remote wl_seat for a Wayland input device.
+ * Returns the remote struct wl_seat for a Wayland input device.
  */
 struct wl_seat *wlr_wl_input_device_get_seat(struct wlr_input_device *dev);
 

include/wlr/backend/x11.h

@@ -11,11 +11,11 @@
 struct wlr_input_device;
 
 /**
- * Creates a new wlr_x11_backend. This backend will be created with no outputs;
- * you must use wlr_x11_output_create to add them.
+ * Creates a new X11 backend. This backend will be created with no outputs;
+ * you must use wlr_x11_output_create() to add them.
  *
  * The `x11_display` argument is the name of the X Display socket. Set
- * to NULL for the default behaviour of XOpenDisplay.
+ * to NULL for the default behaviour of XOpenDisplay().
  */
 struct wlr_backend *wlr_x11_backend_create(struct wl_display *display,
 	const char *x11_display);
@@ -24,27 +24,27 @@ struct wlr_backend *wlr_x11_backend_create(struct wl_display *display,
  * Adds a new output to this backend. You may remove outputs by destroying them.
  * Note that if called before initializing the backend, this will return NULL
  * and your outputs will be created during initialization (and given to you via
- * the output_add signal).
+ * the new_output signal).
  */
 struct wlr_output *wlr_x11_output_create(struct wlr_backend *backend);
 
 /**
- * True if the given backend is a wlr_x11_backend.
+ * Check whether this backend is an X11 backend.
  */
 bool wlr_backend_is_x11(struct wlr_backend *backend);
 
 /**
- * True if the given input device is a wlr_x11_input_device.
+ * Check whether this input device is an X11 input device.
  */
 bool wlr_input_device_is_x11(struct wlr_input_device *device);
 
 /**
- * True if the given output is a wlr_x11_output.
+ * Check whether this output device is an X11 output device.
  */
 bool wlr_output_is_x11(struct wlr_output *output);
 
 /**
- * Sets the title of a wlr_output which is an X11 window.
+ * Sets the title of a struct wlr_output which is an X11 window.
  */
 void wlr_x11_output_set_title(struct wlr_output *output, const char *title);