inc/xrt: Improve xrt_instance documentation

src/xrt/include/xrt/xrt_instance.h

@@ -26,23 +26,65 @@ struct xrt_compositor_fd;
  */
 
 /*!
- * This object acts as a root object for Monado, it either wraps a
+ * This interface acts as a root object for Monado.
- * @ref xrt_prober or forms a connection to a out of process XR service. As
+ * It typically either wraps an @ref xrt_prober or forms a connection to an
- * close to a singleton object there is in Monado, you should not create more
+ * out-of-process XR service.
- * then one of these.
+ *
+ * This is as close to a singleton object as there is in Monado: you should not
+ * create more than one xrt_instance implementation per process.
+ *
+ * Each "target" will provide its own (private) implementation of this
+ * interface, which is exposed by implementing xrt_instance_create().
+ *
+ * Additional information can be found in @ref md_targets
  */
 struct xrt_instance
 {
 	/*!
-	 * Returns the devices of the system represented as @ref xrt_device,
+	 * @name Interface Methods
-	 * see @ref xrt_prober::select, should only be called once.
+	 *
+	 * All implementations of the xrt_instance implementation must
+	 * populate all these function pointers with their implementation
+	 * methods. To use this interface, see the helper functions.
+	 * @{
+	 */
+	/*!
+	 * Returns the devices of the system represented as @ref xrt_device.
+	 *
+	 * Should only be called once.
+	 *
+	 * @note Code consuming this interface should use xrt_instance_select()
+	 *
+	 * @param xinst Pointer to self
+	 * @param[in,out] xdevs Pointer to xrt_device array. Array elements will
+	 * be populated.
+	 * @param[in] num_xdevs The capacity of the @p xdevs array.
+	 *
+	 * @return 0 on success, <0 on error.
+	 *
+	 * @see xrt_prober::probe, xrt_prober::select
 	 */
 	int (*select)(struct xrt_instance *xinst,
 	              struct xrt_device **xdevs,
 	              size_t num_xdevs);
 
 	/*!
-	 * Creates a @ref xrt_compositor_fd, should only be called once.
+	 * Creates a @ref xrt_compositor_fd.
+	 *
+	 * Should only be called once.
+	 *
+	 * @note Code consuming this interface should use
+	 * xrt_instance_create_fd_compositor()
+	 *
+	 * @param xinst Pointer to self
+	 * @param[in] xdev Device to use for creating the compositor
+	 * @param[in] flip_y Whether to flip the direction of the y axis
+	 * @param[out] out_xcfd Pointer to xrt_compositor_fd pointer, will be
+	 * populated.
+	 *
+	 * @return 0 on success, <0 on error.
+	 *
+	 * @see xrt_gfx_provider_create_fd
 	 */
 	int (*create_fd_compositor)(struct xrt_instance *xinst,
 	                            struct xrt_device *xdev,
@@ -50,21 +92,55 @@ struct xrt_instance
 	                            struct xrt_compositor_fd **out_xcfd);
 
 	/*!
-	 * Get the instance @ref xrt_prober, the instance might not be using a
+	 * Get the instance @ref xrt_prober, if any.
-	 * @ref xrt_prober and may return null, the instance still owns the
+	 *
-	 * prober and will destroy it. Can be called multiple times.
+	 * If the instance is not using an @ref xrt_prober, it may return null.
+	 *
+	 * The instance retains ownership of the prober and is responsible for
+	 * destroying it.
+	 *
+	 * Can be called multiple times. (The prober is usually created at
+	 * instance construction time.)
+	 *
+	 * @note Code consuming this interface should use
+	 * xrt_instance_get_prober().
+	 *
+	 * @param xinst Pointer to self
+	 * @param[out] out_xp Pointer to xrt_prober pointer, will be populated
+	 * or set to NULL.
+	 *
+	 * @return 0 on success, <0 on error. (Note that success may mean
+	 * returning a null pointer!)
 	 */
 	int (*get_prober)(struct xrt_instance *xinst,
 	                  struct xrt_prober **out_xp);
 
 	/*!
-	 * Use helper @p xrt_instance_destroy.
+	 * Destroy the instance and its owned objects, including the prober (if
+	 * any).
+	 *
+	 * Code consuming this interface should use xrt_instance_destroy().
+	 *
+	 * @param xinst Pointer to self
 	 */
 	void (*destroy)(struct xrt_instance *xinst);
+	/*!
+	 * @}
+	 */
 };
 
 /*!
- * Helper function for @ref xrt_instance::select, see @ref xrt_prober::select.
+ * @name Method call helpers for xrt_instance
+ * Calling code should prefer using these instead of directly using the function
+ * pointer members.
+ * @{
+ */
+/*!
+ * Helper function for @ref xrt_instance::select.
+ *
+ * See @ref xrt_instance::select for documentation.
+ *
+ * @relates xrt_instance
  */
 static inline int
 xrt_instance_select(struct xrt_instance *xinst,
@@ -76,6 +152,10 @@ xrt_instance_select(struct xrt_instance *xinst,
 
 /*!
  * Helper function for @ref xrt_instance::create_fd_compositor.
+ *
+ * See @ref xrt_instance::create_fd_compositor for documentation.
+ *
+ * @relates xrt_instance
  */
 static inline int
 xrt_instance_create_fd_compositor(struct xrt_instance *xinst,
@@ -88,6 +168,10 @@ xrt_instance_create_fd_compositor(struct xrt_instance *xinst,
 
 /*!
  * Helper function for @ref xrt_instance::get_prober.
+ *
+ * See @ref xrt_instance::get_prober for documentation.
+ *
+ * @relates xrt_instance
  */
 static inline int
 xrt_instance_get_prober(struct xrt_instance *xinst, struct xrt_prober **out_xp)
@@ -97,6 +181,13 @@ xrt_instance_get_prober(struct xrt_instance *xinst, struct xrt_prober **out_xp)
 
 /*!
  * Helper function for @ref xrt_instance::destroy.
+ *
+ * @param[in,out] xinst_ptr A pointer to your instance implementation pointer.
+ *
+ * Will destroy the instance if *xinst_ptr is not NULL. Will then set *xinst_ptr
+ * to NULL.
+ *
+ * @relates xrt_instance
  */
 static inline void
 xrt_instance_destroy(struct xrt_instance **xinst_ptr)
@@ -109,10 +200,30 @@ xrt_instance_destroy(struct xrt_instance **xinst_ptr)
 	xinst->destroy(xinst);
 	*xinst_ptr = NULL;
 }
+/*!
+ * @}
+ */
+
 
 /*!
+ * @name Factory
+ * Implemented in each target.
+ * @{
+ */
+/*!
+ * Create an implementation of the xrt_instance interface.
+ *
  * Creating more then one @ref xrt_instance is probably never the right thing
  * to do, so avoid it.
+ *
+ * Each target must implement this function.
+ *
+ * @param[out] out_xinst A pointer to an xrt_instance pointer. Will be
+ * populated.
+ *
+ * @return 0 on success
+ *
+ * @relates xrt_instance
  */
 int
 xrt_instance_create(struct xrt_instance **out_xinst);
@@ -121,6 +232,10 @@ xrt_instance_create(struct xrt_instance **out_xinst);
  * @}
  */
 
+/*!
+ * @}
+ */
+
 
 #ifdef __cplusplus
 }