[PATCH libdrm 3/3] tests/util: Add some API documentation

[Thierry Reding]

From: Thierry Reding <treding at nvidia.com>

None of the helpers currently have any documentation. Add some to make
it more obvious how these should be used.

Signed-off-by: Thierry Reding <treding at nvidia.com>
---
 tests/util/kms.c | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/tests/util/kms.c b/tests/util/kms.c
index c5d35ab616d1..226386519d49 100644
--- a/tests/util/kms.c
+++ b/tests/util/kms.c
@@ -128,6 +128,13 @@ const char *util_lookup_connector_type_name(unsigned int type)
                                  ARRAY_SIZE(connector_type_names));
 }
 
+/**
+ * Retrieve the name of the kernel driver for a DRM device.
+ *
+ * \param fd the file descriptor of the DRM device
+ *
+ * \return On success, returns the name of the kernel driver.
+ */
 char *util_get_driver(int fd)
 {
     drmVersionPtr version;
@@ -144,6 +151,16 @@ char *util_get_driver(int fd)
     return driver;
 }
 
+/**
+ * Retrieve a list of available DRM devices.
+ *
+ * \param devicesp return location for the list of DRM devices
+ * \param flags bitmask of flags controlling operation
+ *
+ * \return On success, returns the number of devices found. The list of DRM
+ * devices is dynamically allocated and needs to be freed by a call to the
+ * util_free_devices() function.
+ */
 int util_get_devices(drmDevicePtr **devicesp, uint32_t flags)
 {
     drmDevicePtr *devices;
@@ -182,12 +199,32 @@ int util_get_devices(drmDevicePtr **devicesp, uint32_t flags)
     return count;
 }
 
+/**
+ * Free a list of DRM devices.
+ *
+ * \param devices a list of DRM devices, allocated by util_get_devices()
+ * \param count the number of DRM devices in \p devices
+ */
 void util_free_devices(drmDevicePtr *devices, unsigned int count)
 {
     drmFreeDevices(devices, count);
     free(devices);
 }
 
+/**
+ * Opens a DRM device, optionally checking against its kernel driver.
+ *
+ * \param device path to DRM device
+ * \param module optional name of kernel driver
+ *
+ * \return On success, a file descriptor to \p device, or a negative error
+ * code on failure.
+ *
+ * If the caller doesn't care about the kernel driver associated with the DRM
+ * device, then the \p module parameter can be NULL. If \p module is not NULL
+ * this function will retrieve the name of the kernel driver and compare it
+ * to the \p module parameter. If the names don't match, the call will fail.
+ */
 int util_open_with_module(const char *device, const char *module)
 {
     int fd, err = 0;
@@ -229,6 +266,20 @@ out:
     return err;
 }
 
+/**
+ * Opens a DRM device, optionally checking against its kernel driver.
+ *
+ * \param device
+ * \param module
+ *
+ * \return On success, a file descriptor to \p device, or a negative error
+ * code on failure.
+ *
+ * This is similar to util_open_with_module(), except that \p device can be
+ * NULL, in which case all available devices will be tried. If \p module is
+ * specified it will act as a filter. Otherwise the first available device
+ * that can be opened will be used.
+ */
 int util_open(const char *device, const char *module)
 {
     int fd, err;
-- 
2.11.0