diff --git a/include/parrot/io.h b/include/parrot/io.h
index fb692b727c..5fada4fd47 100644
--- a/include/parrot/io.h
+++ b/include/parrot/io.h
@@ -172,25 +172,29 @@ typedef struct _io_vtable {
     io_vtable_get_piohandle get_piohandle;  /* Get the raw file PIOHANDLE */
 } IO_VTABLE;
 
+/* Indices to common IO vtables */
 #define IO_VTABLE_FILEHANDLE        0
 #define IO_VTABLE_PIPE              1
 #define IO_VTABLE_SOCKET            2
 #define IO_VTABLE_STRINGHANDLE      3
 #define IO_VTABLE_USER              4
 
-#define IO_PTR_IDX_VTABLE 0
-#define IO_PTR_IDX_READ_BUFFER 1
-#define IO_PTR_IDX_WRITE_BUFFER 2
+/* get_pointer values for common io-related pointer values.
+   ALL IO handle types MUST implement get_pointer and MUST respond to these
+   values. */
+#define IO_PTR_IDX_VTABLE           0
+#define IO_PTR_IDX_READ_BUFFER      1
+#define IO_PTR_IDX_WRITE_BUFFER     2
 
 /* Specify that the buffer may be any size */
 #define BUFFER_SIZE_ANY     (size_t)-1
 #define BUFFER_FLAGS_ANY    (INTVAL)0
 
+/* Helpful wrappers to get common pointers from IO handle PMCs */
 #define IO_GET_VTABLE(i, p) ((const IO_VTABLE *)VTABLE_get_pointer_keyed_int((i), (p), IO_PTR_IDX_VTABLE))
 #define IO_GET_READ_BUFFER(i, p) ((IO_BUFFER *)VTABLE_get_pointer_keyed_int((i), (p), IO_PTR_IDX_READ_BUFFER))
 #define IO_GET_WRITE_BUFFER(i, p) ((IO_BUFFER *)VTABLE_get_pointer_keyed_int((i), (p), IO_PTR_IDX_WRITE_BUFFER))
 
-
 /* io/api.c - Public API functions */
 /* HEADERIZER BEGIN: src/io/api.c */
 /* Don't modify between HEADERIZER BEGIN / HEADERIZER END.  Your changes will be lost. */
diff --git a/src/io/io_private.h b/src/io/io_private.h
index 55dcd7aad9..d210f13b0a 100644
--- a/src/io/io_private.h
+++ b/src/io/io_private.h
@@ -56,7 +56,7 @@ src/io/stringhandle.c:
     IO VTABLE definitions for stringhandle-related operations. StringHandle
     PMC methods and related IO API calls will invoke these functions.
 
-src/io/userobject.c:
+src/io/userhandle.c:
     IO VTABLE definitions for user-defined and PBC-level IO objects. These
     are the IO operations that will be used for a user-defined IO object that
     does not directly inherit from FileHandle, Socket, or Handle.
@@ -87,15 +87,23 @@ src/platform/X/socket.c:
 
 DIAGRAM
 
-    IO API (api.c)
-         |
-         |
-         |      [                     PRIVATE                      ]
-         +----> IO VTABLEs -----> Buffers -----> Low-Level Interface
-         |
-         |
-         |
-    IO PMCs
+    IO PMCs         (src/pmc/*handle.pmc)
+        |
+        v
+    IO API          (src/io/api.c)
+        |
+        v
+    Utilities       (src/io/utilities.c)
+        |
+        v
+    Buffers         (src/io/buffer.c)
+        |
+        v
+    IO VTABLES      (src/io/filehandle.c, pipe.c, stringhandle.c, socket.c)
+        |
+        v
+    Low-Level Platform
+    Interface       (src/platform/XXX/file.c, io.c, socket.c)
 
 */
 
@@ -110,8 +118,9 @@ DIAGRAM
 #define PIO_STRING_BUFFER_MINSIZE 32
 
 #define PIO_BUFFER_MIN_SIZE       2048  /* Smallest size for a block buffer */
-#define PIO_BUFFER_LINEBUF_SIZE   256   /* Smallest size for a line buffer */
+#define PIO_BUFFER_LINEBUF_SIZE   256   /* Smallest size for a line buffer  */
 
+/* Interp-level IO system data */
 struct _ParrotIOData {
     PMC ** table;               /* Standard IO Streams (STDIN, STDOUT, STDERR) */
     INTVAL num_vtables;         /* Number of vtables */
@@ -145,9 +154,6 @@ struct _ParrotIOData {
         PARROT_ASSERT((b)->buffer_ptr <= (b)->buffer_start); \
         PARROT_ASSERT((b)->buffer_start <= (b)->buffer_end); \
         PARROT_ASSERT((b)->buffer_end <= (b)->buffer_ptr + (b)->buffer_size); \
-        /*PARROT_ASSERT(BUFFER_FREE_HEAD_SPACE(b) >= 0);*/ \
-        /*PARROT_ASSERT(BUFFER_FREE_END_SPACE(b) >= 0);*/ \
-        /*PARROT_ASSERT(BUFFER_USED_SIZE(b) >= 0);*/ \
         PARROT_ASSERT(BUFFER_FREE_HEAD_SPACE(b) + BUFFER_USED_SIZE(b) + BUFFER_FREE_END_SPACE(b) == (b)->buffer_size); \
     } while (0);
 
@@ -157,6 +163,8 @@ struct _ParrotIOData {
         fprintf(stderr, "\t\t\t = %d\n", BUFFER_FREE_HEAD_SPACE(b) + BUFFER_USED_SIZE(b) + BUFFER_FREE_END_SPACE(b)); \
     } while (0);
 
+/* Get an editable version of the IO_VTABLE structure, typically used during
+   vtable initialization. */
 #define IO_EDITABLE_IO_VTABLE(i, idx) ((IO_VTABLE *)(void *)(&((i)->piodata->vtables[(idx)])))