Extra menu comments

Admin:
  Part of submission from Martin Avison. Not tagged.

rlib/c/menu

@@ -51,10 +51,10 @@
 
 typedef struct menu__str {
   wimp_menuhdr *m;         /* the wimp-level menu that we've built. */
-  int nitems;
+  int nitems;              /* items in menu */
   void *entryspace;        /* for sub-menus, and entries with >12 chars */
-  int nbytes;
-  int maxentrywidth;
+  int nbytes;              /* bytes used in entryspace */
+  int maxentrywidth;       /* used to set menu width */
 } menu__str;
 /* concrete representation of abstract menu object */
 
@@ -80,7 +80,7 @@ into the allocation of store and then the copying of data, so that the copy
 into the larger buffer can share the latter half of the operation. */
 
 static void menu__disposespace(menu m)
-{
+{ /* Free two areas (header+icons & indirect data) for a complete menu */
   if (m->m != 0) {
     free(m->m);
     m->m = 0;
@@ -173,7 +173,7 @@ static void menu__copyworkarea(menu__workarea *w /*in*/, menu m /*out*/)
 /* -------- Creating menu descriptions. -------- */
 
 static void menu__initmenu(char *name, menu m /*out*/)
-{
+{ /* Create and initialise menu structure, block and entryspace */
   int i;
   for (i=0; i<12; i++) {
     m->m->title[i] = name[i];
@@ -193,6 +193,7 @@ static int menu__max(int a, int b)
 
 static wimp_menuitem *menu__additem(
   menu__workarea *w /*out*/, char *name, int length)
+/* Add an item to the end of a menu                    */
 /* The returned pointer can be used to set flags, etc. */
 {
   wimp_menuitem *ptr;
@@ -207,6 +208,7 @@ static wimp_menuitem *menu__additem(
       /* in OS units, 16 per char. */
   }
   if (length <= 12) {
+    /* item can be directly in the icon, so copy to icon block. */
     int i;
     for (i=0; i<length; i++) {ptr->data.text[i] = name[i];}
     if (length < 12) {ptr->data.text[length] = 0;}
@@ -214,10 +216,12 @@ static wimp_menuitem *menu__additem(
     /* no room for the text: unlikely */
     ptr = menu__itemptr(&w->m, w->m.nitems-1); /* fudge */
   } else {
+    /* space for length, so set up icon block to be indirect */
     ptr->iconflags += wimp_INDIRECT;
     ptr->data.indirecttext.buffer = ((char*)w->m.entryspace) + w->m.nbytes;
     ptr->data.indirecttext.validstring = (char*) -1;
     ptr->data.indirecttext.bufflen = 100;
+    /* copy name into entryspace */
     (void) memmove(((char*)w->m.entryspace) + w->m.nbytes, name, length);
     w->m.nbytes += length + 1;
     ((char*)w->m.entryspace)[w->m.nbytes-1] = 0; /* terminate the string. */
@@ -275,7 +279,6 @@ static void menu__getopt(parser *p)
 }
 
 static void menu__getname (parser *p)
-
 { /*Skip leading spaces*/
   while (p->ch == ' ')
     p->ch = *p->s++;
@@ -407,7 +410,7 @@ static void menu__doextend(menu__workarea *w, char *descr)
 /* -------- Entrypoints. -------- */
 
 menu menu_new(char *name, char *descr)
-{
+{ /* Create a new menu from the list of entries in descr */
   menu m;
   menu__workarea menu__w;
   wimp_menuitem *ptr;
@@ -431,7 +434,7 @@ menu menu_new(char *name, char *descr)
 }
 
 void menu_dispose(menu *m, int recursive)
-{
+{ /* Free the storage associated with a menu - and optionally submenus. */
   if (recursive != 0) {
     menu *a = (menu*) ((*m)->entryspace);
     while (1) {
@@ -445,7 +448,7 @@ void menu_dispose(menu *m, int recursive)
 }
 
 void menu_extend(menu m, char *descr)
-{
+{ /* Add one (or more) items from descr to existing menu. */
   menu__workarea menu__w;
   menu__copytoworkarea(m, &menu__w);
   menu__doextend(&menu__w, descr);
@@ -453,7 +456,7 @@ void menu_extend(menu m, char *descr)
 }
 
 void menu_setflags(menu m, int entry, int tick, int fade)
-{
+{ /* Set/Unset tick and fade flags on specific menu entry */
   wimp_menuitem *p;
   if (entry == 0) {return;}
   if (entry > m->nitems) {return;}
@@ -515,7 +518,7 @@ void menu_make_sprite(menu m, int entry, char *spritename)
 
 
 void menu_submenu(menu m, int place, menu submenu)
-{
+{ /* Link a submenu to an entry in a parent menu */
   int i;
   wimp_menuitem *p = menu__itemptr(m, place-1);
   menu__workarea menu__w;