Document most of they key binding system.

include/QF/keys.h

@@ -482,14 +482,14 @@ typedef enum {
 } knum_t;
 
 typedef enum {
-	key_unfocused,			// engine has lost input focus
-	key_game,
-	key_demo,
-	key_console,
-	key_message,
-	key_menu,
+	key_unfocused,			///< engine has lost input focus
+	key_game,				///< Normal in-game key bindings
+	key_demo,				///< Demo playback key bindings
+	key_console,			///< Command console key bindings
+	key_message,			///< Message input line key bindings
+	key_menu,				///< Menu key bindings.
 
-	key_last				// enum size
+	key_last				///< enum size
 } keydest_t;
 
 #ifndef __QFCC__
@@ -515,34 +515,141 @@ typedef struct imt_s {
 	int         written;			///< avoid duplicate config file writes
 } imt_t;
 
+/**	Chain of input mapping tables ascociated with a keydest sub-system (game,
+	menu, etc).
+*/
 typedef struct keytarget_s {
-	imt_t      *imts;
-	imt_t      *active;
+	imt_t      *imts;				///< list of tables attached to this target
+	imt_t      *active;				///< currently active table in this target
 } keytarget_t;
 
 extern int		keydown[QFK_LAST];
 
+struct cbuf_s;
+
+void Key_Init (struct cbuf_s *cb);
+void Key_Init_Cvars (void);
+
+/**	Find an Input Mapping Table by name.
+
+	Searches through all keydest targets for the named imt. The search is case
+	insensitive.
+
+	\param imt_name	The name of the imt to find. Case insensitive.
+	\return			The named imt, or null if not found.
+*/
 imt_t *Key_FindIMT (const char *imt_name);
+
+/**	Create a new imt and attach it to the specified keydest target.
+
+	The name of the new imt must be unique (case insensitive) across all
+	keydest targets. This is to simplify the in_bind command.
+
+	If \a chain_imt_name is not null, then it species the fallback imt for when
+	the key is not bound in the new imt. It must be an already existing imt in
+	the specified keydest target. This is to prevent loops and other weird
+	behavior.
+
+	\param kd		The keydest target to which the new imt will be attached.
+	\param imt_name	The name for the new imt. Must be unique (case
+					insensitive).
+	\param chain_imt_name	The name of the fallback imt if not null. Must
+					already exist on the specified keydest target.
+*/
 void Key_CreateIMT (keydest_t kd, const char *imt_name,
 					const char *chain_imt_name);
 
-struct cbuf_s;
+/**	Handle a key press/release event.
+
+	\param key		The key that was pressed or released for this event.
+	\param unicode	The unicode value of the key.
+	\param down		True if a press event, false if a release event.
+*/
 void Key_Event (knum_t key, short unicode, qboolean down);
+
+/**	Handle loss or gain of input focus (usually in windowed enviroments).
+
+	Sets the keydest target to key_unfocuses when input focus is lost.
+
+	Triggers keydest callbacks.
+
+	\bug			Always sets the target to key_game when focus is gained.
+
+	\param gain		True if focus is gained, false if focus is lost.
+*/
 void Key_FocusEvent (int gain);
-void Key_Init (struct cbuf_s *cb);
-void Key_Init_Cvars (void);
+
 void Key_WriteBindings (QFile *f);
+
+/**	Force all key states to unpressed.
+
+	Sends a key release event for any keys that are seen as down.
+*/
 void Key_ClearStates (void);
+
+/**	Return a key binding in the specified input mapping table.
+
+	\param imt		The input mapping table from which to get the binding.
+	\param key		The key for which to get the binding.
+	\return			The command string bound to the key, or null if unbound.
+*/
 const char *Key_GetBinding (imt_t *imt, knum_t key);
+
+/** Bind a command string to a key in the specified input mapping table.
+
+	Only one command string can be bound to a key, but the command string may
+	contain multiple commands.
+
+	\param int		The input mapping table in which the key will be bound.
+	\param keynum	The key to which the command string will be bound.
+	\param binding	The command string that will be bound.
+*/
 void Key_SetBinding (imt_t *imt, knum_t keynum, const char *binding);
+
+/**	Set the current keydest target.
+
+	Triggers keydest callbacks.
+
+	\param kd		The keydest target to make current.
+*/
 void Key_SetKeyDest(keydest_t kd);
-typedef void keydest_callback_t (keydest_t);
+
+/** keydest callback signature.
+
+	\param kd		The new current keydest target.
+*/
+typedef void keydest_callback_t (keydest_t kd);
+
+/**	Add a callback for when the keydest target changes.
+
+	\param callback	The callback to be added.
+*/
 void Key_KeydestCallback (keydest_callback_t *callback);
 
+/**	Get the string representation of a key.
 
+	Returns a string (a QFK_* name) for the given keynum.
+
+	\param keynum	The key for which to get the string.
+	\return			The string representation of the key.
+*/
 const char *Key_KeynumToString (knum_t keynum);
+
+/**	Get the keynum for the named key.
+
+	Returns a key number to be used to index keybindings[] by looking at
+	the given string.  Single ascii characters return themselves, while
+	the QFK_* names are matched up.
+
+	\param str		The name of the key.
+	\return			The named key if valid, otherwise -1
+*/
 int Key_StringToKeynum (const char *str);
+
 struct progs_s;
+
+/**	Add the Key builtins to the specified progs instance.
+*/
 void Key_Progs_Init (struct progs_s *pr);
 #endif
 

libs/video/targets/keys.c

@@ -634,10 +634,6 @@ Key_Game (knum_t key, short unicode)
 		imt = imt->chain;
 	}
 	return false;
-/*
-	Sys_DPrintf("kb %p, key_target %d, key_dest %d, key %d\n", kb,
-				key_target, key_dest, key);
-*/
 }
 
 /*
@@ -655,15 +651,6 @@ Key_Console (knum_t key, short unicode)
 	Con_KeyEvent (key, unicode, keydown[key]);
 }
 
-//============================================================================
-
-/*
-  Key_StringToKeynum
-
-  Returns a key number to be used to index keybindings[] by looking at
-  the given string.  Single ascii characters return themselves, while
-  the QFK_* names are matched up.
-*/
 VISIBLE int
 Key_StringToKeynum (const char *str)
 {
@@ -679,12 +666,6 @@ Key_StringToKeynum (const char *str)
 	return -1;
 }
 
-/*
-  Key_KeynumToString
-
-  Returns a string (a QFK_* name) for the given keynum.
-  FIXME: handle quote special (general escape sequence?)
-*/
 VISIBLE const char *
 Key_KeynumToString (knum_t keynum)
 {