Add some explanatory comments

5 files changed, 103 insertions, 12 deletions

diff --git a/keycodes.c b/keycodes.c
index 792a263..f452f7b 100644
--- a/keycodes.c
+++ b/keycodes.c
@@ -739,11 +739,11 @@ HandleKeycodesFile(XkbFile * file,
                                        HandleKeycodesFile))
                 info->errorCount++;
             break;
-        case StmtKeycodeDef:
+        case StmtKeycodeDef: /* e.g. <ESC> = 9; */
             if (!HandleKeycodeDef((KeycodeDef *) stmt, merge, info))
                 info->errorCount++;
             break;
-        case StmtKeyAliasDef:
+        case StmtKeyAliasDef: /* e.g. alias <MENU> = <COMP>; */
             if (!HandleAliasDef((KeyAliasDef *) stmt,
                                 merge, info->fileID, &info->aliases))
                 info->errorCount++;
@@ -752,7 +752,7 @@ HandleKeycodesFile(XkbFile * file,
             if (!HandleKeyNameVar((VarDef *) stmt, merge, info))
                 info->errorCount++;
             break;
-        case StmtIndicatorNameDef:
+        case StmtIndicatorNameDef: /* e.g. indicator 1 = "Caps Lock"; */
             if (!HandleIndicatorNameDef((IndicatorNameDef *) stmt,
                                         merge, info))
             {
diff --git a/misc.c b/misc.c
index ceae7f5..d1dc832 100644
--- a/misc.c
+++ b/misc.c
@@ -49,6 +49,8 @@ ProcessIncludeFile(IncludeStmt * stmt,
     rtrn = XkbFindFileInCache(stmt->file, file_type, &stmt->path);
     if (rtrn == NULL)
     {
+        /* file not in cache, open it, parse it and store it in cache for next
+           time. */
         file = XkbFindFileInPath(stmt->file, file_type, &stmt->path);
         if (file == NULL)
         {
@@ -62,6 +64,7 @@ ProcessIncludeFile(IncludeStmt * stmt,
         setScanState(stmt->file, 1);
         if (debugFlags & 2)
             INFO1("About to parse include file %s\n", stmt->file);
+        /* parse the file */
         if ((XKBParseFile(file, &rtrn) == 0) || (rtrn == NULL))
         {
             setScanState(oldFile, oldLine);
diff --git a/symbols.c b/symbols.c
index 7c1807a..883285e 100644
--- a/symbols.c
+++ b/symbols.c
@@ -61,7 +61,7 @@ extern Atom tok_KEYPAD;
 typedef struct _KeyInfo
 {
     CommonInfo defs;
-    unsigned long name;
+    unsigned long name; /* the 4 chars of the key name, as long */
     unsigned char groupInfo;
     unsigned char typesDefined;
     unsigned char symsDefined;
@@ -78,6 +78,9 @@ typedef struct _KeyInfo
     Atom dfltType;
 } KeyInfo;
 
+/**
+ * Init the given key info to sane values.
+ */
 static void
 InitKeyInfo(KeyInfo * info)
 {
@@ -108,6 +111,9 @@ InitKeyInfo(KeyInfo * info)
     return;
 }
 
+/**
+ * Free memory associated with this key info and reset to sane values.
+ */
 static void
 FreeKeyInfo(KeyInfo * info)
 {
@@ -136,9 +142,15 @@ FreeKeyInfo(KeyInfo * info)
     info->vmodmap = 0;
     info->nameForOverlayKey = 0;
     info->repeat = RepeatUndefined;
+    info->allowNone = 0;
     return;
 }
 
+/**
+ * Copy old into new, optionally reset old to 0.
+ * If old is reset, new simply re-uses old's memory. Otherwise, the memory is
+ * newly allocated and new points to the new memory areas.
+ */
 static Bool
 CopyKeyInfo(KeyInfo * old, KeyInfo * new, Bool clearOld)
 {
diff --git a/xkbcomp.c b/xkbcomp.c
index 80268b0..d79f11a 100644
--- a/xkbcomp.c
+++ b/xkbcomp.c
@@ -868,7 +868,7 @@ extern int yydebug;
 int
 main(int argc, char *argv[])
 {
-    FILE *file;
+    FILE *file;         /* input file (or stdin) */
     XkbFile *rtrn;
     XkbFile *mapToUse;
     int ok;
@@ -953,12 +953,12 @@ main(int argc, char *argv[])
     {
         ok = True;
         setScanState(inputFile, 1);
-        if ((inputFormat == INPUT_XKB)
+        if ((inputFormat == INPUT_XKB) /* parse .xkb file */
             && (XKBParseFile(file, &rtrn) && (rtrn != NULL)))
         {
             fclose(file);
             mapToUse = rtrn;
-            if (inputMap != NULL)
+            if (inputMap != NULL) /* map specified on cmdline? */
             {
                 while ((mapToUse)
                        && (!uStringEqual(mapToUse->name, inputMap)))
@@ -974,6 +974,7 @@ main(int argc, char *argv[])
             }
             else if (rtrn->common.next != NULL)
             {
+                /* look for map with XkbLC_Default flag. */
                 mapToUse = rtrn;
                 for (; mapToUse; mapToUse = (XkbFile *) mapToUse->common.next)
                 {
@@ -1034,7 +1035,7 @@ main(int argc, char *argv[])
                 break;
             }
         }
-        else if (inputFormat == INPUT_XKM)
+        else if (inputFormat == INPUT_XKM) /* parse xkm file */
         {
             unsigned tmp;
             bzero((char *) &result, sizeof(result));
diff --git a/xkbpath.c b/xkbpath.c
index fc3d4f0..74ae850 100644
--- a/xkbpath.c
+++ b/xkbpath.c
@@ -42,14 +42,40 @@
 #define	PATH_MAX 1024
 #endif
 
-#define	PATH_CHUNK	8
+#define	PATH_CHUNK	8       /* initial szPath */
 
 static Bool noDefaultPath = False;
 static int longestPath;
-static int szPath;
-static int nPathEntries;
-static char **includePath;
+static int szPath;         /* number of entries allocated for includePath */
+static int nPathEntries;   /* number of actual entries in includePath */
+static char **includePath; /* Holds all directories we might be including data from */
 
+/**
+ * Extract the first token from an include statement.
+ * @param str_inout Input statement, modified in-place. Can be passed in
+ * repeatedly. If str_inout is NULL, the parsing has completed.
+ * @param file_rtrn Set to the include file to be used.
+ * @param map_rtrn Set to whatever comes after ), if any.
+ * @param nextop_rtrn Set to the next operation in the complete statement.
+ * @param extra_data Set to the string between ( and ), if any.
+ *
+ * @return True if parsing was succcessful, False for an illegal string.
+ *
+ * Example: "evdev+aliases(qwerty)"
+ *      str_inout = aliases(qwerty)
+ *      nextop_retrn = +
+ *      extra_data = NULL
+ *      file_rtrn = evdev
+ *      map_rtrn = NULL
+ *
+ * 2nd run with "aliases(qwerty)"
+ *      str_inout = NULL
+ *      file_rtrn = aliases
+ *      map_rtrn = qwerty
+ *      extra_data = NULL
+ *      nextop_retrn = ""
+ *
+ */
 Bool
 XkbParseIncludeMap(char **str_inout, char **file_rtrn, char **map_rtrn,
                    char *nextop_rtrn, char **extra_data)
@@ -71,9 +97,11 @@ XkbParseIncludeMap(char **str_inout, char **file_rtrn, char **map_rtrn,
     }
     else
     {
+        /* search for tokens inside the string */
         next = strpbrk(str, "|+");
         if (next)
         {
+            /* set nextop_rtrn to \0, next to next character */
             *nextop_rtrn = *next;
             *next++ = '\0';
         }
@@ -82,6 +110,7 @@ XkbParseIncludeMap(char **str_inout, char **file_rtrn, char **map_rtrn,
             *nextop_rtrn = '\0';
             next = NULL;
         }
+        /* search for :, store result in extra_data */
         tmp = strchr(str, ':');
         if (tmp != NULL)
         {
@@ -128,6 +157,9 @@ XkbParseIncludeMap(char **str_inout, char **file_rtrn, char **map_rtrn,
     return True;
 }
 
+/**
+ * Init memory for include paths.
+ */
 Bool
 XkbInitIncludePath(void)
 {
@@ -146,6 +178,9 @@ XkbAddDefaultDirectoriesToPath(void)
     XkbAddDirectoryToPath(DFLT_XKB_CONFIG_ROOT);
 }
 
+/**
+ * Remove all entries from the global includePath.
+ */
 void
 XkbClearIncludePath(void)
 {
@@ -168,6 +203,10 @@ XkbClearIncludePath(void)
     return;
 }
 
+/**
+ * Add the given path to the global includePath variable.
+ * If dir is NULL, the includePath is emptied.
+ */
 Bool
 XkbAddDirectoryToPath(const char *dir)
 {
@@ -212,6 +251,10 @@ XkbAddDirectoryToPath(const char *dir)
 
 /***====================================================================***/
 
+/**
+ * Return the xkb directory based on the type.
+ * Do not free the memory returned by this function.
+ */
 char *
 XkbDirectoryForInclude(unsigned type)
 {
@@ -263,6 +306,19 @@ typedef struct _FileCacheEntry
 } FileCacheEntry;
 static FileCacheEntry *fileCache;
 
+/**
+ * Add the file with the given name to the internal cache to avoid opening and
+ * parsing the file multiple times. If a cache entry for the same name + type
+ * is already present, the entry is overwritten and the data belonging to the
+ * previous entry is returned.
+ *
+ * @parameter name The name of the file (e.g. evdev).
+ * @parameter type Type of the file (XkbTypesIdx, ... or XkbSemanticsFile, ...)
+ * @parameter path The full path to the file.
+ * @parameter data Already parsed data.
+ *
+ * @return The data from the overwritten file or NULL.
+ */
 void *
 XkbAddFileToCache(char *name, unsigned type, char *path, void *data)
 {
@@ -292,6 +348,15 @@ XkbAddFileToCache(char *name, unsigned type, char *path, void *data)
     return NULL;
 }
 
+/**
+ * Search for the given name + type in the cache.
+ *
+ * @parameter name The name of the file (e.g. evdev).
+ * @parameter type Type of the file (XkbTypesIdx, ... or XkbSemanticsFile, ...)
+ * @parameter pathRtrn Set to the full path of the given entry.
+ *
+ * @return the data from the cache entry or NULL if no matching entry was found.
+ */
 void *
 XkbFindFileInCache(char *name, unsigned type, char **pathRtrn)
 {
@@ -310,6 +375,16 @@ XkbFindFileInCache(char *name, unsigned type, char **pathRtrn)
 
 /***====================================================================***/
 
+/**
+ * Search for the given file name in the include directories.
+ *
+ * @param type one of XkbTypesIndex, XkbCompatMapIndex, ..., or
+ * XkbSemanticsFile, XkmKeymapFile, ...
+ * @param pathReturn is set to the full path of the file if found.
+ *
+ * @return an FD to the file or NULL. If NULL is returned, the value of
+ * pathRtrn is undefined.
+ */
 FILE *
 XkbFindFileInPath(char *name, unsigned type, char **pathRtrn)
 {