From 901254b9aceecf653b978e28d67a7419e4965da2 Mon Sep 17 00:00:00 2001
From: Ryan Pavlik <ryan.pavlik@collabora.com>
Date: Tue, 18 Jun 2019 14:09:16 -0500
Subject: [PATCH] aux/util: Improve docs for calloc wrappers

---
 src/xrt/auxiliary/util/u_misc.h | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/src/xrt/auxiliary/util/u_misc.h b/src/xrt/auxiliary/util/u_misc.h
index d9b6025eb..5c99962fd 100644
--- a/src/xrt/auxiliary/util/u_misc.h
+++ b/src/xrt/auxiliary/util/u_misc.h
@@ -9,7 +9,7 @@
 
 #pragma once
 
-#include <stdlib.h>
+#include <stdlib.h> // for calloc
 #include <string.h> // for memset
 
 #ifdef __cplusplus
@@ -21,6 +21,9 @@ extern "C" {
  * Allocate and zero the give size and casts the memory into a pointer of the
  * given type.
  *
+ * Use instead of a bare calloc, but only when U_TYPED_CALLOC and
+ * U_TYPED_ARRAY_CALLOC do not meet your needs.
+ *
  * @ingroup aux_util
  */
 #define U_CALLOC_WITH_CAST(TYPE, SIZE) ((TYPE *)calloc(1, SIZE))
@@ -29,6 +32,8 @@ extern "C" {
  * Allocate and zero the space required for some type, and cast the return type
  * appropriately.
  *
+ * Use instead of a bare calloc when allocating a single structure.
+ *
  * @ingroup aux_util
  */
 #define U_TYPED_CALLOC(TYPE) ((TYPE *)calloc(1, sizeof(TYPE)))
@@ -37,6 +42,9 @@ extern "C" {
  * Allocate and zero the space required for some type, and cast the return type
  * appropriately.
  *
+ * Use instead of a bare calloc when allocating an array of a type.
+ * This includes allocating C strings: pass char as the type.
+ *
  * @ingroup aux_util
  */
 #define U_TYPED_ARRAY_CALLOC(TYPE, COUNT)                                      \
@@ -45,7 +53,7 @@ extern "C" {
 /*!
  * Zeroes the correct amount of memory based on the type pointed-to by the
  * argument.
- * 
+ *
  * Use instead of memset(..., 0, ...) on a structure or pointer to structure.
  *
  * @ingroup aux_util
@@ -55,7 +63,7 @@ extern "C" {
 /*!
  * Zeroes the correct amount of memory based on the type and size of the static
  * array named in the argument.
- * 
+ *
  * Use instead of memset(..., 0, ...) on an array.
  *
  * @ingroup aux_util