Improve wlr_drm_format documentation

A wlroots user can easily get confused and think that `cap` refers to
wlroots buffer capabilities, not array capacity.

1 files changed, 21 insertions, 2 deletions

diff --git a/include/wlr/render/drm_format_set.h b/include/wlr/render/drm_format_set.h
index 15d4eea3..cb367a63 100644
--- a/include/wlr/render/drm_format_set.h
+++ b/include/wlr/render/drm_format_set.h
@@ -5,19 +5,38 @@
 #include <stddef.h>
 #include <stdint.h>
 
+/** A single DRM format */
 struct wlr_drm_format {
+	// The actual DRM format, from `drm_fourcc.h`
 	uint32_t format;
-	size_t len, cap;
+	// The number of modifiers
+	size_t len;
+	// The capacity of the array; do not use.
+	size_t capacity;
+	// The actual modifiers
 	uint64_t modifiers[];
 };
 
+/** A set of DRM formats */
 struct wlr_drm_format_set {
-	size_t len, cap;
+	// The number of formats
+	size_t len;
+	// The capacity of the array; private to wlroots
+	size_t capacity;
+	// A pointer to an array of `struct wlr_drm_format *` of length `len`.
 	struct wlr_drm_format **formats;
 };
 
+/**
+ * Free all of the DRM formats in the set, making the set empty.  Does not
+ * free the set itself.
+ */
 void wlr_drm_format_set_finish(struct wlr_drm_format_set *set);
 
+/**
+ * Return a pointer to a member of this `wlr_drm_format_set` of format
+ * `format`, or NULL if none exists.
+ */
 const struct wlr_drm_format *wlr_drm_format_set_get(
 	const struct wlr_drm_format_set *set, uint32_t format);