Write some more docs

6 files changed, 61 insertions, 1 deletions

diff --git a/include/wlr/backend.h b/include/wlr/backend.h
index 00dc9fdc..e3b14add 100644
--- a/include/wlr/backend.h
+++ b/include/wlr/backend.h
@@ -11,16 +11,39 @@ struct wlr_backend {
 	const struct wlr_backend_impl *impl;
 
 	struct {
+		/** Raised when destroyed, passed the wlr_backend reference */
 		struct wl_signal destroy;
+		/** Raised when new inputs are added, passed the wlr_input_device */
 		struct wl_signal new_input;
+		/** Raised when new outputs are added, passed the 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.
+ * Returns NULL on failure.
+ */
 struct wlr_backend *wlr_backend_autocreate(struct wl_display *display);
+/**
+ * Start the backend. This may signal new_input or new_output immediately, but
+ * may also wait until the display's event loop begins. Returns false on
+ * failure.
+ */
 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.
+ */
 void wlr_backend_destroy(struct wlr_backend *backend);
+/**
+ * Obtains the wlr_egl reference this backend is using.
+ */
 struct wlr_egl *wlr_backend_get_egl(struct wlr_backend *backend);
+/**
+ * Obtains the wlr_renderer reference this backend is using.
+ */
 struct wlr_renderer *wlr_backend_get_renderer(struct wlr_backend *backend);
 
 uint32_t usec_to_msec(uint64_t usec);
diff --git a/include/wlr/backend/drm.h b/include/wlr/backend/drm.h
index 90460647..0c9e5c8b 100644
--- a/include/wlr/backend/drm.h
+++ b/include/wlr/backend/drm.h
@@ -6,6 +6,13 @@
 #include <wlr/backend/session.h>
 #include <wlr/types/wlr_output.h>
 
+/**
+ * Creates a DRM backend using the specified GPU file descriptor (typically from
+ * a device node in /dev/dri).
+ *
+ * To slave this to another DRM backend, pass it as the parent (which _must_ be
+ * a DRM backend, other kinds of backends raise SIGABRT).
+ */
 struct wlr_backend *wlr_drm_backend_create(struct wl_display *display,
 	struct wlr_session *session, int gpu_fd, struct wlr_backend *parent);
 
diff --git a/include/wlr/backend/headless.h b/include/wlr/backend/headless.h
index 8995f7cb..ee784a0d 100644
--- a/include/wlr/backend/headless.h
+++ b/include/wlr/backend/headless.h
@@ -5,9 +5,23 @@
 #include <wlr/types/wlr_input_device.h>
 #include <wlr/types/wlr_output.h>
 
+/**
+ * Creates a headless backend. A headless backend has no outputs or inputs by
+ * default.
+ */
 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.
+ */
 struct wlr_output *wlr_headless_add_output(struct wlr_backend *backend,
 	unsigned int width, unsigned int height);
+/**
+ * Creates a new input device. The caller is responsible for manually raising
+ * any event signals on the new input device if it wants to simulate input
+ * events.
+ */
 struct wlr_input_device *wlr_headless_add_input_device(
 	struct wlr_backend *backend, enum wlr_input_device_type type);
 bool wlr_backend_is_headless(struct wlr_backend *backend);
diff --git a/include/wlr/backend/interface.h b/include/wlr/backend/interface.h
index d9212795..f03e95d9 100644
--- a/include/wlr/backend/interface.h
+++ b/include/wlr/backend/interface.h
@@ -12,6 +12,10 @@ struct wlr_backend_impl {
 	struct wlr_renderer *(*get_renderer)(struct wlr_backend *backend);
 };
 
+/**
+ * Initializes common state on a wlr_backend and sets the implementation to the
+ * provided wlr_backend_impl reference.
+ */
 void wlr_backend_init(struct wlr_backend *backend,
 		const struct wlr_backend_impl *impl);
 
diff --git a/include/wlr/backend/libinput.h b/include/wlr/backend/libinput.h
index c7cfe894..92d31415 100644
--- a/include/wlr/backend/libinput.h
+++ b/include/wlr/backend/libinput.h
@@ -9,7 +9,9 @@
 
 struct wlr_backend *wlr_libinput_backend_create(struct wl_display *display,
 		struct wlr_session *session);
-struct libinput_device *wlr_libinput_get_device_handle(struct wlr_input_device *dev);
+/** Gets the underlying libinput_device handle for the given wlr_input_device */
+struct libinput_device *wlr_libinput_get_device_handle(
+		struct wlr_input_device *dev);
 
 bool wlr_backend_is_libinput(struct wlr_backend *backend);
 bool wlr_input_device_is_libinput(struct wlr_input_device *device);
diff --git a/include/wlr/backend/multi.h b/include/wlr/backend/multi.h
index 2dee7403..842eed67 100644
--- a/include/wlr/backend/multi.h
+++ b/include/wlr/backend/multi.h
@@ -4,11 +4,21 @@
 #include <wlr/backend.h>
 #include <wlr/backend/session.h>
 
+/**
+ * Creates a multi-backend. Multi-backends wrap an arbitrary number of backends
+ * and aggregate their new_output/new_input signals.
+ */
 struct wlr_backend *wlr_multi_backend_create(struct wl_display *display);
+/**
+ * Adds the given backend to the multi backend. This should be done before the
+ * new backend is started.
+ */
 void wlr_multi_backend_add(struct wlr_backend *multi,
 	struct wlr_backend *backend);
+
 void wlr_multi_backend_remove(struct wlr_backend *multi,
 	struct wlr_backend *backend);
+
 bool wlr_backend_is_multi(struct wlr_backend *backend);
 struct wlr_session *wlr_multi_get_session(struct wlr_backend *base);
 bool wlr_multi_is_empty(struct wlr_backend *backend);