Add comments about sizes of dynamically allocated arrays

Many arrays have sz_* or size_* fields to list the number of entries
allocated, and num_* fields to record the number of entries used.

Others use num_* for the number allocated, or size based on max_key_code.

And a few are just plain trying to mess with your head.  (I'm looking at
you XkbNamesRec & XkbKeyTypeRec.)

It sure would have been nice if all the XKB authors could have picked
a single convention and stuck to it, but we're 20 years too late for
that now, so just document it so I can stop reverse engineering from
the code every time I need to see if we got a bounds check right or not.

Signed-off-by: Alan Coopersmith <alan.coopersmith@oracle.com>

1 files changed, 5 insertions, 0 deletions

diff --git a/XKBgeom.h b/XKBgeom.h
index f603852..cef78fa 100644
--- a/XKBgeom.h
+++ b/XKBgeom.h
@@ -95,6 +95,11 @@ typedef struct	_XkbBounds {
 #define	XkbBoundsWidth(b)	(((b)->x2)-((b)->x1))
 #define	XkbBoundsHeight(b)	(((b)->y2)-((b)->y1))
 
+/*
+ * In the following structs, this pattern is used for dynamically sized arrays:
+ * foo is an array for which sz_foo entries are allocated & num_foo are used
+ */
+
 typedef struct _XkbOutline {
 	unsigned short	num_points;
 	unsigned short	sz_points;