Index: kernel/generic/src/ipc/irq.c
===================================================================
--- kernel/generic/src/ipc/irq.c	(revision 3422fb6a2a8e483c3294e3bfbd50bd1dc755217c)
+++ kernel/generic/src/ipc/irq.c	(revision a5d014333511885041ef3899f34c8d8e21ef7605)
@@ -37,7 +37,8 @@
  *
  * This framework allows applications to subscribe to receive a notification
- * when interrupt is detected. The application may provide a simple 'top-half'
- * handler as part of its registration, which can perform simple operations
- * (read/write port/memory, add information to notification IPC message).
+ * when an interrupt is detected. The application may provide a simple
+ * 'top-half' handler as part of its registration, which can perform simple
+ * operations (read/write port/memory, add information to notification IPC
+ * message).
  *
  * The structure of a notification message is as follows:
@@ -50,23 +51,4 @@
  * - in_phone_hash: interrupt counter (may be needed to assure correct order
  *                  in multithreaded drivers)
- *
- * Note on synchronization for ipc_irq_subscribe(), ipc_irq_unsubscribe(),
- * ipc_irq_cleanup() and IRQ handlers:
- *
- *   By always taking all of the uspace IRQ hash table lock, IRQ structure lock
- *   and answerbox lock, we can rule out race conditions between the
- *   registration functions and also the cleanup function. Thus the observer can
- *   either see the IRQ structure present in both the hash table and the
- *   answerbox list or absent in both. Views in which the IRQ structure would be
- *   linked in the hash table but not in the answerbox list, or vice versa, are
- *   not possible.
- *
- *   By always taking the hash table lock and the IRQ structure lock, we can
- *   rule out a scenario in which we would free up an IRQ structure, which is
- *   still referenced by, for example, an IRQ handler. The locking scheme forces
- *   us to lock the IRQ structure only after any progressing IRQs on that
- *   structure are finished. Because we hold the hash table lock, we prevent new
- *   IRQs from taking new references to the IRQ structure.
- *
  */
 
@@ -119,5 +101,5 @@
 	}
 	
-	/* Rewrite the pseudocode addresses from physical to kernel virtual. */
+	/* Rewrite the IRQ code addresses from physical to kernel virtual. */
 	for (size_t i = 0; i < cmdcount; i++) {
 		uintptr_t addr;
@@ -177,8 +159,7 @@
 }
 
-/** Statically check the top-half pseudocode
- *
- * Check the top-half pseudocode for invalid or unsafe
- * constructs.
+/** Statically check the top-half IRQ code
+ *
+ * Check the top-half IRQ code for invalid or unsafe constructs.
  *
  */
@@ -217,7 +198,7 @@
 }
 
-/** Free the top-half pseudocode.
- *
- * @param code Pointer to the top-half pseudocode.
+/** Free the top-half IRQ code.
+ *
+ * @param code Pointer to the top-half IRQ code.
  *
  */
@@ -232,9 +213,9 @@
 }
 
-/** Copy the top-half pseudocode from userspace into the kernel.
- *
- * @param ucode Userspace address of the top-half pseudocode.
- *
- * @return Kernel address of the copied pseudocode.
+/** Copy the top-half IRQ code from userspace into the kernel.
+ *
+ * @param ucode Userspace address of the top-half IRQ code.
+ *
+ * @return Kernel address of the copied IRQ code.
  *
  */
@@ -294,7 +275,6 @@
  * @param box     Receiving answerbox.
  * @param inr     IRQ number.
- * @param imethod Interface and method to be associated with the
- *                notification.
- * @param ucode   Uspace pointer to top-half pseudocode.
+ * @param imethod Interface and method to be associated with the notification.
+ * @param ucode   Uspace pointer to top-half IRQ code.
  *
  * @return  IRQ capability handle.
@@ -342,6 +322,8 @@
 	
 	/*
-	 * Enlist the IRQ structure in the uspace IRQ hash table and the
-	 * answerbox's list and make the IRQ capability valid.
+	 * Insert the IRQ structure into the uspace IRQ hash table and retype
+	 * the capability. By retyping the capability inside the critical
+	 * section, we make sure another thread cannot attempt to unregister the
+	 * IRQ before it is inserted into the hash table.
 	 */
 	irq_spinlock_lock(&irq_uspace_hash_table_lock, true);
@@ -373,4 +355,5 @@
 		return ENOENT;
 	}
+	/* Make sure only one thread can win the race to unsubscribe. */
 	cap->type = CAP_TYPE_ALLOCATED;
 	irq_spinlock_unlock(&TASK->lock, true);
@@ -389,5 +372,5 @@
 	irq_spinlock_unlock(&irq_uspace_hash_table_lock, true);
 	
-	/* Free up the pseudo code and associated structures. */
+	/* Free up the IRQ code and associated structures. */
 	code_free(irq->notif_cfg.code);
 	
@@ -415,10 +398,10 @@
 }
 
-/** Apply the top-half pseudo code to find out whether to accept the IRQ or not.
+/** Apply the top-half IRQ code to find out whether to accept the IRQ or not.
  *
  * @param irq IRQ structure.
  *
- * @return IRQ_ACCEPT if the interrupt is accepted by the
- *         pseudocode, IRQ_DECLINE otherwise.
+ * @return IRQ_ACCEPT if the interrupt is accepted by the IRQ code.
+ * @return IRQ_DECLINE if the interrupt is not accepted byt the IRQ code.
  *
  */