From b5d4bc3c62886f3e089165bd4d82bae781a6bda3 Mon Sep 17 00:00:00 2001
From: Demi Marie Obenour <demi@invisiblethingslab.com>
Date: Mon, 15 Nov 2021 09:44:12 -0500
Subject: [PATCH] Improve wlr_drm_format documentation

A wlroots user can easily get confused and think that `cap` refers to
wlroots buffer capabilities, not array capacity.
---
 include/wlr/render/drm_format_set.h | 23 ++++++++++++++++++++--
 render/drm_format_set.c             | 30 ++++++++++++++---------------
 2 files changed, 36 insertions(+), 17 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);
 
diff --git a/render/drm_format_set.c b/render/drm_format_set.c
index bd8f0cb7..3edc1925 100644
--- a/render/drm_format_set.c
+++ b/render/drm_format_set.c
@@ -15,7 +15,7 @@ void wlr_drm_format_set_finish(struct wlr_drm_format_set *set) {
 	free(set->formats);
 
 	set->len = 0;
-	set->cap = 0;
+	set->capacity = 0;
 	set->formats = NULL;
 }
 
@@ -74,8 +74,8 @@ bool wlr_drm_format_set_add(struct wlr_drm_format_set *set, uint32_t format,
 		return false;
 	}
 
-	if (set->len == set->cap) {
-		size_t new = set->cap ? set->cap * 2 : 4;
+	if (set->len == set->capacity) {
+		size_t new = set->capacity ? set->capacity * 2 : 4;
 
 		struct wlr_drm_format **tmp = realloc(set->formats,
 			sizeof(*fmt) + sizeof(fmt->modifiers[0]) * new);
@@ -85,7 +85,7 @@ bool wlr_drm_format_set_add(struct wlr_drm_format_set *set, uint32_t format,
 			return false;
 		}
 
-		set->cap = new;
+		set->capacity = new;
 		set->formats = tmp;
 	}
 
@@ -94,15 +94,15 @@ bool wlr_drm_format_set_add(struct wlr_drm_format_set *set, uint32_t format,
 }
 
 struct wlr_drm_format *wlr_drm_format_create(uint32_t format) {
-	size_t cap = 4;
+	size_t capacity = 4;
 	struct wlr_drm_format *fmt =
-		calloc(1, sizeof(*fmt) + sizeof(fmt->modifiers[0]) * cap);
+		calloc(1, sizeof(*fmt) + sizeof(fmt->modifiers[0]) * capacity);
 	if (!fmt) {
 		wlr_log_errno(WLR_ERROR, "Allocation failed");
 		return NULL;
 	}
 	fmt->format = format;
-	fmt->cap = cap;
+	fmt->capacity = capacity;
 	return fmt;
 }
 
@@ -119,16 +119,16 @@ bool wlr_drm_format_add(struct wlr_drm_format **fmt_ptr, uint64_t modifier) {
 		}
 	}
 
-	if (fmt->len == fmt->cap) {
-		size_t cap = fmt->cap ? fmt->cap * 2 : 4;
+	if (fmt->len == fmt->capacity) {
+		size_t capacity = fmt->capacity ? fmt->capacity * 2 : 4;
 
-		fmt = realloc(fmt, sizeof(*fmt) + sizeof(fmt->modifiers[0]) * cap);
+		fmt = realloc(fmt, sizeof(*fmt) + sizeof(fmt->modifiers[0]) * capacity);
 		if (!fmt) {
 			wlr_log_errno(WLR_ERROR, "Allocation failed");
 			return false;
 		}
 
-		fmt->cap = cap;
+		fmt->capacity = capacity;
 		*fmt_ptr = fmt;
 	}
 
@@ -137,9 +137,9 @@ bool wlr_drm_format_add(struct wlr_drm_format **fmt_ptr, uint64_t modifier) {
 }
 
 struct wlr_drm_format *wlr_drm_format_dup(const struct wlr_drm_format *format) {
-	assert(format->len <= format->cap);
+	assert(format->len <= format->capacity);
 	size_t format_size = sizeof(struct wlr_drm_format) +
-		format->cap * sizeof(format->modifiers[0]);
+		format->capacity * sizeof(format->modifiers[0]);
 	struct wlr_drm_format *duped_format = malloc(format_size);
 	if (duped_format == NULL) {
 		return NULL;
@@ -171,12 +171,12 @@ struct wlr_drm_format *wlr_drm_format_intersect(
 		return NULL;
 	}
 	format->format = a->format;
-	format->cap = format_cap;
+	format->capacity = format_cap;
 
 	for (size_t i = 0; i < a->len; i++) {
 		for (size_t j = 0; j < b->len; j++) {
 			if (a->modifiers[i] == b->modifiers[j]) {
-				assert(format->len < format->cap);
+				assert(format->len < format->capacity);
 				format->modifiers[format->len] = a->modifiers[i];
 				format->len++;
 				break;