xrt: Improve docs, fixing doxygen warnings

src/xrt/include/xrt/xrt_compositor.h

@@ -389,10 +389,12 @@ struct xrt_swapchain
 	 * See xrAcquireSwapchainImage.
 	 *
 	 * Caller must make sure that no image is acquired before calling
-	 * acquire_image.
+	 * @ref xrt_swapchain_acquire_image.
 	 *
 	 * @param xsc Self pointer
 	 * @param[out] out_index Image index to use next
+	 *
+	 * Call @ref xrt_swapchain_wait_image before writing to the image index output from this function.
 	 */
 	xrt_result_t (*acquire_image)(struct xrt_swapchain *xsc, uint32_t *out_index);
 
@@ -461,9 +463,9 @@ xrt_swapchain_acquire_image(struct xrt_swapchain *xsc, uint32_t *out_index)
  * @public @memberof xrt_swapchain
  */
 static inline xrt_result_t
-xrt_swapchain_wait_image(struct xrt_swapchain *xsc, uint64_t timeout, uint32_t index)
+xrt_swapchain_wait_image(struct xrt_swapchain *xsc, uint64_t timeout_ns, uint32_t index)
 {
-	return xsc->wait_image(xsc, timeout, index);
+	return xsc->wait_image(xsc, timeout_ns, index);
 }
 
 /*!

src/xrt/include/xrt/xrt_defines.h

@@ -715,6 +715,7 @@ enum xrt_input_type
 enum xrt_input_name
 {
 	// clang-format off
+	//! Standard pose used for rendering
 	XRT_INPUT_GENERIC_HEAD_POSE                  = XRT_INPUT_NAME(0x0000, POSE),
 	XRT_INPUT_GENERIC_HEAD_DETECT                = XRT_INPUT_NAME(0x0001, BOOLEAN),
 	XRT_INPUT_GENERIC_HAND_TRACKING_LEFT         = XRT_INPUT_NAME(0x0002, HAND_TRACKING),

src/xrt/include/xrt/xrt_instance.h

@@ -132,9 +132,9 @@ struct xrt_instance
 static inline xrt_result_t
 xrt_instance_create_system(struct xrt_instance *xinst,
                            struct xrt_system_devices **out_xsysd,
-                           struct xrt_system_compositor **out_xsc)
+                           struct xrt_system_compositor **out_xsysc)
 {
-	return xinst->create_system(xinst, out_xsysd, out_xsc);
+	return xinst->create_system(xinst, out_xsysd, out_xsysc);
 }
 
 /*!

src/xrt/include/xrt/xrt_prober.h

@@ -47,6 +47,11 @@ struct os_hid_device;
  */
 #define XRT_MAX_DEVICES_PER_PROBE 16
 
+/*!
+ * The maximum number of @ref xrt_auto_prober instances that can be handled.
+ *
+ * @ingroup xrt_iface
+ */
 #define XRT_MAX_AUTO_PROBERS 16
 
 /*!
@@ -101,6 +106,12 @@ struct xrt_prober_device
 /*!
  * Callback for listing video devices.
  *
+ * @param xp Prober
+ * @param pdev Prober device being iterated
+ * @param product Product string, if available
+ * @param manufacturer Manufacturer string, if available
+ * @param serial Serial number string, if available
+ * @param ptr Your opaque userdata pointer as provided to @ref xrt_prober_list_video_devices
  * @ingroup xrt_iface
  */
 typedef void (*xrt_prober_list_video_func_t)(struct xrt_prober *xp,
@@ -133,17 +144,16 @@ struct xrt_prober
 	 * to detect any additional devices that may show up once the first
 	 * device has been been started.
 	 *
-	 * @note Code consuming this interface should use xrt_prober_probe()
 	 * @see xrt_prober::lock_list, xrt_prober::unlock_list
 	 */
 	xrt_result_t (*probe)(struct xrt_prober *xp);
 
 	/*!
-	 * Locks the prober list of probed devices and returns it, while locked
+	 * Locks the prober list of probed devices and returns it.
-	 * calling @ref xrt_prober::probe is forbidden. Not thread safe.
+	 * While locked, calling @ref xrt_prober::probe is forbidden. Not thread safe.
+	 *
 	 * See @ref xrt_prober::probe for more detailed expected usage.
 	 *
-	 * @note Code consuming this interface should use xrt_prober_lock_list()
 	 * @see xrt_prober::probe, xrt_prober::unlock_list
 	 */
 	xrt_result_t (*lock_list)(struct xrt_prober *xp,
@@ -155,7 +165,6 @@ struct xrt_prober
 	 * Takes a pointer to the list pointer and clears it. Not thread safe.
 	 * See @ref xrt_prober::probe for more detailed expected usage.
 	 *
-	 * @note Code consuming this interface should use xrt_prober_unlock_list()
 	 * @see xrt_prober::probe, xrt_prober::lock_list
 	 */
 	xrt_result_t (*unlock_list)(struct xrt_prober *xp, struct xrt_prober_device ***devices);
@@ -206,6 +215,16 @@ struct xrt_prober
 	 */
 	int (*select)(struct xrt_prober *xp, struct xrt_device **xdevs, size_t xdev_capacity);
 
+	/*!
+	 * Open a HID (Human Interface Device) interface using native HID support.
+	 *
+	 * @param xp Pointer to self
+	 * @param xpdev prober device
+	 * @param iface HID interface number
+	 * @param[out] out_hid_dev instance of @ref os_hid_device for the given interface
+	 *
+	 * @return 0 on success, <0 on error.
+	 */
 	int (*open_hid_interface)(struct xrt_prober *xp,
 	                          struct xrt_prober_device *xpdev,
 	                          int iface,
@@ -220,8 +239,28 @@ struct xrt_prober
 	                         struct xrt_frame_context *xfctx,
 	                         struct xrt_fs **out_xfs);
 
+	/*!
+	 * Iterate through available video devices, calling your callback @p cb with your userdata @p ptr.
+	 *
+	 * @param xp Pointer to self
+	 * @param cb Callback function
+	 * @param ptr Opaque pointer for your userdata, passed through to the callback.
+	 *
+	 * @see xrt_prober_list_video_func_t
+	 * @return 0 on success, <0 on error.
+	 */
 	int (*list_video_devices)(struct xrt_prober *xp, xrt_prober_list_video_func_t cb, void *ptr);
 
+	/*!
+	 * Retrieve the raw @ref xrt_prober_entry and @ref xrt_auto_prober arrays.
+	 *
+	 * @param xp Pointer to self
+	 * @param[out] out_entry_count The size of @p out_entries
+	 * @param[out] out_entries An array of prober entries
+	 * @param[out] out_auto_probers An array of up to @ref XRT_MAX_AUTO_PROBERS auto-probers
+	 *
+	 * @return 0 on success, <0 on error.
+	 */
 	int (*get_entries)(struct xrt_prober *xp,
 	                   size_t *out_entry_count,
 	                   struct xrt_prober_entry ***out_entries,
@@ -246,6 +285,14 @@ struct xrt_prober
 	                             unsigned char *out_buffer,
 	                             size_t max_length);
 
+	/*!
+	 * Determine whether a prober device can be opened.
+	 *
+	 * @param xp Pointer to self
+	 * @param xpdev prober device
+	 *
+	 * @return true if @p xpdev can be opened.
+	 */
 	bool (*can_open)(struct xrt_prober *xp, struct xrt_prober_device *xpdev);
 
 	/*!
@@ -558,9 +605,9 @@ static inline xrt_result_t
 xrt_builder_estimate_system(struct xrt_builder *xb,
                             cJSON *config,
                             struct xrt_prober *xp,
-                            struct xrt_builder_estimate *estimate)
+                            struct xrt_builder_estimate *out_estimate)
 {
-	return xb->estimate_system(xb, config, xp, estimate);
+	return xb->estimate_system(xb, config, xp, out_estimate);
 }
 
 /*!

src/xrt/include/xrt/xrt_results.h

@@ -1,4 +1,4 @@
-// Copyright 2020, Collabora, Ltd.
+// Copyright 2020-2022, Collabora, Ltd.
 // SPDX-License-Identifier: BSL-1.0
 /*!
  * @file
@@ -9,8 +9,20 @@
 
 #pragma once
 
+/*!
+ * Result type used across Monado.
+ *
+ * 0 is @ref XRT_SUCCESS, positive values are "special" non-error return codes (like timeout), negative values are
+ * errors.
+ *
+ * @see u_pp_xrt_result
+ * @ingroup xrt_iface
+ */
 typedef enum xrt_result
 {
+	/*!
+	 * The operation succeeded
+	 */
 	XRT_SUCCESS = 0,
 
 	/*!
@@ -20,11 +32,33 @@ typedef enum xrt_result
 	 */
 	XRT_TIMEOUT = 2,
 
+	/*!
+	 * A problem occurred either with the IPC transport itself, with invalid commands from the client, or with
+	 * invalid responses from the server.
+	 */
 	XRT_ERROR_IPC_FAILURE = -1,
+
+	/*!
+	 * Returned when trying to acquire or release an image and there is no image left to acquire/no space in the
+	 * queue left to release to
+	 */
 	XRT_ERROR_NO_IMAGE_AVAILABLE = -2,
+
+	/*!
+	 * Other unspecified error related to Vulkan
+	 */
 	XRT_ERROR_VULKAN = -3,
+
+	/*!
+	 * Other unspecified error related to OpenGL
+	 */
 	XRT_ERROR_OPENGL = -4,
+
+	/*!
+	 * The function tried to submit Vulkan commands but received an error.
+	 */
 	XRT_ERROR_FAILED_TO_SUBMIT_VULKAN_COMMANDS = -5,
+
 	/*!
 	 *
 	 * Returned when a swapchain create flag is passed that is valid, but
@@ -35,45 +69,55 @@ typedef enum xrt_result
 	 * isn't supported.
 	 */
 	XRT_ERROR_SWAPCHAIN_FLAG_VALID_BUT_UNSUPPORTED = -6,
+
 	/*!
 	 * Could not allocate native image buffer(s).
 	 */
 	XRT_ERROR_ALLOCATION = -7,
+
 	/*!
 	 * The pose is no longer active, this happens when the application
 	 * tries to access a pose that is no longer active.
 	 */
 	XRT_ERROR_POSE_NOT_ACTIVE = -8,
+
 	/*!
 	 * Creating a fence failed.
 	 */
 	XRT_ERROR_FENCE_CREATE_FAILED = -9,
+
 	/*!
 	 * Getting or giving the native fence handle caused a error.
 	 */
 	XRT_ERROR_NATIVE_HANDLE_FENCE_ERROR = -10,
+
 	/*!
 	 * Multiple not supported on this layer level (IPC, compositor).
 	 */
 	XRT_ERROR_MULTI_SESSION_NOT_IMPLEMENTED = -11,
+
 	/*!
 	 * The requested format is not supported by Monado.
 	 */
 	XRT_ERROR_SWAPCHAIN_FORMAT_UNSUPPORTED = -12,
+
 	/*!
 	 * The given config was EGL_NO_CONFIG_KHR and EGL_KHR_no_config_context
 	 * is not supported by the display.
 	 */
 	XRT_ERROR_EGL_CONFIG_MISSING = -13,
+
 	/*!
 	 * Failed to initialize threading components.
 	 */
 	XRT_ERROR_THREADING_INIT_FAILURE = -14,
+
 	/*!
 	 * The client has not created a session on this IPC connection,
 	 * which is needed for the given command.
 	 */
 	XRT_ERROR_IPC_SESSION_NOT_CREATED = -15,
+
 	/*!
 	 * The client has already created a session on this IPC connection.
 	 */