[PATCH:kbproto 1/2] Add comments about sizes of dynamically allocated arrays

[Alan Coopersmith]

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 at oracle.com>
---
 XKBgeom.h |    5 +++++
 XKBstr.h  |   21 +++++++++++++++++++++
 2 files changed, 26 insertions(+)

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;
diff --git a/XKBstr.h b/XKBstr.h
index 25c0cec..1146908 100644
--- a/XKBstr.h
+++ b/XKBstr.h
@@ -92,9 +92,12 @@ typedef struct _XkbKeyType {
 	XkbModsRec		mods;
 	unsigned char	  	num_levels;
 	unsigned char	  	map_count;
+	/* map is an array of map_count XkbKTMapEntryRec structs */
 	XkbKTMapEntryPtr  	map;
+	/* preserve is an array of map_count XkbModsRec structs */
 	XkbModsPtr  		preserve;
 	Atom		  	name;
+	/* level_names is an array of num_levels Atoms */
 	Atom *			level_names;
 } XkbKeyTypeRec, *XkbKeyTypePtr;
 
@@ -298,10 +301,14 @@ typedef	struct _XkbControls {
 #define	XkbAX_NeedFeedback(c,w)	(XkbAX_AnyFeedback(c)&&XkbAX_NeedOption(c,w))
 
 typedef struct _XkbServerMapRec {
+	/* acts is an array of XkbActions structs, with size_acts entries
+	   allocated, and num_acts entries used. */
 	unsigned short		 num_acts;
 	unsigned short		 size_acts;
 	XkbAction		*acts;
 
+	/* behaviors, key_acts, explicit, & vmodmap are all arrays with
+	   (xkb->max_key_code + 1) entries allocated for each. */
 	XkbBehavior		*behaviors;
 	unsigned short		*key_acts;
 #if defined(__cplusplus) || defined(c_plusplus)
@@ -328,15 +335,20 @@ typedef	struct _XkbSymMapRec {
 } XkbSymMapRec, *XkbSymMapPtr;
 
 typedef struct _XkbClientMapRec {
+	/* types is an array of XkbKeyTypeRec structs, with size_types entries
+	   allocated, and num_types entries used. */
 	unsigned char		 size_types;
 	unsigned char		 num_types;
 	XkbKeyTypePtr		 types;
 
+	/* syms is an array of size_syms KeySyms, in which num_syms are used */
 	unsigned short		 size_syms;
 	unsigned short		 num_syms;
 	KeySym			*syms;
+	/* key_sym_map is an array of (max_key_code + 1) XkbSymMapRec structs */
 	XkbSymMapPtr		 key_sym_map;
 
+	/* modmap is an array of (max_key_code + 1) unsigned chars */
 	unsigned char		*modmap;
 } XkbClientMapRec, *XkbClientMapPtr;
 
@@ -364,6 +376,8 @@ typedef struct _XkbSymInterpretRec {
 } XkbSymInterpretRec,*XkbSymInterpretPtr;
 
 typedef struct _XkbCompatMapRec {
+	/* sym_interpret is an array of XkbSymInterpretRec structs,
+	   in which size_si are allocated & num_si are used. */
 	XkbSymInterpretPtr	 sym_interpret;
 	XkbModsRec		 groups[XkbNumKbdGroups];
 	unsigned short		 num_si;
@@ -413,11 +427,15 @@ typedef struct _XkbNamesRec {
 	Atom		  vmods[XkbNumVirtualMods];
 	Atom		  indicators[XkbNumIndicators];
 	Atom		  groups[XkbNumKbdGroups];
+	/* keys is an array of (xkb->max_key_code + 1) XkbKeyNameRec entries */
 	XkbKeyNamePtr	  keys;
+	/* key_aliases is an array of num_key_aliases XkbKeyAliasRec entries */
 	XkbKeyAliasPtr	  key_aliases;
+	/* radio_groups is an array of num_rg Atoms */
 	Atom		 *radio_groups;
 	Atom		  phys_symbols;
 
+	/* num_keys seems to be unused in libX11 */
 	unsigned char	  num_keys;
 	unsigned char	  num_key_aliases;
 	unsigned short	  num_rg;
@@ -592,6 +610,7 @@ typedef struct _XkbDeviceInfo {
 	unsigned short		supported;
 	unsigned short		unsupported;
 
+	/* btn_acts is an array of num_btn XkbAction entries */
 	unsigned short		num_btns;
 	XkbAction *		btn_acts;
 
@@ -599,6 +618,8 @@ typedef struct _XkbDeviceInfo {
 	unsigned short		num_leds;
 	unsigned short		dflt_kbd_fb;
 	unsigned short		dflt_led_fb;
+	/* leds is an array of XkbDeviceLedInfoRec in which
+	   sz_leds entries are allocated and num_leds entries are used */
 	XkbDeviceLedInfoPtr	leds;
 } XkbDeviceInfoRec,*XkbDeviceInfoPtr;
 
-- 
1.7.9.2