Index: mod/kmem/heapa.fn.c
==================================================================
--- mod/kmem/heapa.fn.c
+++ mod/kmem/heapa.fn.c
@@ -29,10 +29,19 @@
 		kmbox* header;
 	} region;
 	/* we need to allocate space for the
 	 * header and for the actual object */
 	sz region_size = sizeof(kmbox) + len;
+
+	/* kmres reply is the struct that shall be returned by the
+	 * function. if an error-condition occurs, the appropriate
+	 * error code should be determined through system-specific
+	 * means, the pointer value should be set to null, and the
+	 * object should be returned immediately. if the object is
+	 * not returned from within the system-specific section it
+	 * will then be filled out with the appropriate values for
+	 * a successful allocation and returned to the caller. */
 	kmres reply;
 
 #	ifdef KFenv_posix
 		/* posix  APIs  - we've  got  it  easy. currently  for
 		 * nonlinear  heap  allocation   kmheapa  simply  uses
@@ -58,13 +67,14 @@
 			posix_prot_read | posix_prot_write,
 			posix_flag_anonymous | posix_map_shared,
 			-1, 0
 		};
 
-		/* impl note: while per manpage fd is "ignored"
-		 * for MAP_ANONYMOUS, "some implementations" require
-		 * a value of -1 */
+		/* impl note: while per manpage fd is "ignored" for
+		 * MAP_ANONYMOUS,  "some implementations" require a
+		 * value of -1, so we're setting it to that just to
+		 * be safe. */
 
 		struct k_platform_syscall_answer r = k_platform_syscall
 			(k_platform_syscall_mmap, Kmsz(args), args);
 
 		if (r.error == 0) region.byte = (ubyte*)r.ret; else {
@@ -80,10 +90,14 @@
 		}
 #	else
  	   Knoimpl(kmheapa,KVos);
 #		error missing implementation
 #	endif
+
+	/* if the system-specific code has not returned early,
+	 * we assume success and return the new pointer to the
+	 * calling function along with a success code. */
 	
 	void* const object = (region.byte + sizeof (kmbox));
 
 	region.header -> kind = kmkind_heap;
 	region.header -> size = len;