diff --git a/src/register/table-gtk.h b/src/register/table-gtk.h
index cfddaed88e..d220fd23c0 100644
--- a/src/register/table-gtk.h
+++ b/src/register/table-gtk.h
@@ -9,6 +9,16 @@
  *
  * It provides the mechanism to handle tab-traversal.
  *
+ * hack alert -- this file and the corresponding one
+ * for motif share some basic comon code.  
+ * C++ style inheritance from a coon base class would
+ * solve this problem, but with just C, there is no easy
+ * way to accomplish this. 
+ *
+ * In particular, the file table-motif.h contains a fair
+ * amount of documentation for these comon parts ...
+ *
+ *
  * HISTORY:
  * Copyright (c) 1998 Linas Vepstas
  * Copyright (c) 1998 Rob Browning <rlb@cs.utexas.edu>
@@ -31,8 +41,8 @@
 \********************************************************************/
 
 
-#ifndef __XACC_TABLE_H__
-#define __XACC_TABLE_H__
+#ifndef __XACC_TABLE_GTK_H__
+#define __XACC_TABLE_GTK_H__
 
 #include <gtk/gtk.h>
 #include "basiccell.h"
@@ -138,7 +148,7 @@ Table     * xaccMallocTable (void);
 void        xaccInitTable (Table *);
 void        xaccDestroyTable (Table *);
 
-/* rsize the table to the indicated dimensions.
+/* resize the table to the indicated dimensions.
  * calls the gui-independent xaccTableResize() routine,
  * and then does some gtk-specific cleanup.
  */
@@ -152,5 +162,5 @@ void        xaccNextTabGroup (Table *, GtkWidget*);
 /* redraw the table GUI */
 void        xaccRefreshTableGUI (Table *);
 
-#endif __XACC_TABLE_H__
+#endif __XACC_TABLE_GTK_H__
 /* ================== end of file ======================= */
diff --git a/src/register/table-motif.h b/src/register/table-motif.h
index 3a04b77ba1..6d4971391d 100644
--- a/src/register/table-motif.h
+++ b/src/register/table-motif.h
@@ -30,8 +30,8 @@
 \********************************************************************/
 
 
-#ifndef __XACC_TABLE_H__
-#define __XACC_TABLE_H__
+#ifndef __XACC_TABLE_MOTIF_H__
+#define __XACC_TABLE_MOTIF_H__
 
 #include <Xm/Xm.h>
 #include "basiccell.h"
@@ -58,17 +58,26 @@ struct _Locator {
 
 typedef struct _Locator Locator;
 
+/* The number of "physical" rows/cols is the number
+ * of displayed one-line gui rows/cols in the table.
+ * The number of physical rows can differ from the 
+ * number of "virtual" rows because each virtual row 
+ * consist of one or more physical rows.
+ *
+ * Given the location of a physical row & col, the corresponding 
+ * virtual row & col can be found by looking it up in the 
+ * "locators" member.  The locator will provide the matching 
+ * virtual row and column.  
+ *
+ * Given the location of the virtual row and column, the
+ * corresponding GUI handler, and any associated user data can 
+ * be directly accessed.
+ */
+
 typedef struct _Table Table;
 
 struct _Table {
 
-  /* The number of "physical" rows/cols is the number
-   * of displayed one-line gui rows/cols in the table.
-   * The number of physical rows can differ from the 
-   * number of "virtual" rows because each virtual row 
-   * consist of one or more physical rows.
-   */
-
   int num_phys_rows;
   int num_phys_cols;
   int num_virt_rows;
@@ -127,9 +136,10 @@ Table     * xaccMallocTable (void);
 void        xaccInitTable (Table *);
 void        xaccDestroyTable (Table *);
 
-/* rsize the table to the indicated dimensions.
- * calls the gui-independent xaccTableResize() routine,
- * and then does some motif-specific cleanup.
+/* The xaccSetTableSize() method will resize the table to the 
+ * indicated dimensions.  This method calls the gui-independent 
+ * xaccTableResize() routine, and then does some motif-specific 
+ * cleanup.
  */
 void        xaccSetTableSize (Table * table, int phys_rows, int phys_cols,
                                              int virt_rows, int virt_cols);
@@ -141,5 +151,5 @@ void        xaccNextTabGroup (Table *, Widget);
 /* redraw the table GUI */
 void        xaccRefreshTableGUI (Table *);
 
-#endif __XACC_TABLE_H__
+#endif __XACC_TABLE_MOTIF_H__
 /* ================== end of file ======================= */