Index: kernel/generic/src/ddi/irq.c
===================================================================
--- kernel/generic/src/ddi/irq.c	(revision 39b0a51454b0612c72d33b798ecc3c89ee13b849)
+++ kernel/generic/src/ddi/irq.c	(revision ee50130e3b1d50789ddf63162191a85cf20298f8)
@@ -34,7 +34,6 @@
  * @brief IRQ dispatcher.
  *
- * This file provides means of connecting IRQs with particular
- * devices and logic for dispatching interrupts to IRQ handlers
- * defined by those devices.
+ * This file provides means of connecting IRQs with particular devices and logic
+ * for dispatching interrupts to IRQ handlers defined by those devices.
  *
  * This code is designed to support:
@@ -46,24 +45,21 @@
  * Note about architectures.
  *
- * Some architectures has the term IRQ well defined. Examples
- * of such architectures include amd64, ia32 and mips32. Some
- * other architectures, such as sparc64, don't use the term
- * at all. In those cases, we boldly step forward and define what
- * an IRQ is.
- *
- * The implementation is generic enough and still allows the
- * architectures to use the hardware layout effectively.
- * For instance, on amd64 and ia32, where there is only 16
- * IRQs, the irq_hash_table can be optimized to a one-dimensional
- * array. Next, when it is known that the IRQ numbers (aka INR's)
- * are unique, the claim functions can always return IRQ_ACCEPT.
+ * Some architectures have the term IRQ well defined. Examples of such
+ * architectures include amd64, ia32 and mips32. Some other architectures, such
+ * as sparc64, don't use the term at all. In those cases, we boldly step forward
+ * and define what an IRQ is.
+ *
+ * The implementation is generic enough and still allows the architectures to
+ * use the hardware layout effectively.  For instance, on amd64 and ia32, where
+ * there is only 16 IRQs, the irq_hash_table can be optimized to a
+ * one-dimensional array. Next, when it is known that the IRQ numbers (aka
+ * INR's) are unique, the claim functions can always return IRQ_ACCEPT.
  *
  *
  * Note about the irq_hash_table.
  *
- * The hash table is configured to use two keys: inr and devno.
- * However, the hash index is computed only from inr. Moreover,
- * if devno is -1, the match is based on the return value of
- * the claim() function instead of on devno.
+ * The hash table is configured to use two keys: inr and devno.  However, the
+ * hash index is computed only from inr. Moreover, if devno is -1, the match is
+ * based on the return value of the claim() function instead of on devno.
  */
 
@@ -102,7 +98,6 @@
 
 /**
- * Hash table operations for cases when we know that
- * there will be collisions between different keys.
- *
+ * Hash table operations for cases when we know that there will be collisions
+ * between different keys.
  */
 static size_t irq_ht_hash(sysarg_t *key);
@@ -117,9 +112,7 @@
 
 /**
- * Hash table operations for cases when we know that
- * there will be no collisions between different keys.
- * However, there might be still collisions among
+ * Hash table operations for cases when we know that there will be no collisions
+ * between different keys.  However, there might be still collisions among
  * elements with single key (sharing of one IRQ).
- *
  */
 static size_t irq_lin_hash(sysarg_t *key);
@@ -151,8 +144,8 @@
 
 	/*
-	 * Be smart about the choice of the hash table operations.
-	 * In cases in which inrs equals the requested number of
-	 * chains (i.e. where there is no collision between
-	 * different keys), we can use optimized set of operations.
+	 * Be smart about the choice of the hash table operations.  In cases in
+	 * which inrs equals the requested number of chains (i.e. where there is
+	 * no collision between different keys), we can use optimized set of
+	 * operations.
 	 */
 	if (inrs == chains) {
@@ -188,11 +181,8 @@
 /** Register IRQ for device.
  *
- * The irq structure must be filled with information
- * about the interrupt source and with the claim()
- * function pointer and handler() function pointer.
+ * The irq structure must be filled with information about the interrupt source
+ * and with the claim() function pointer and handler() function pointer.
  *
  * @param irq IRQ structure belonging to a device.
- *
- * @return True on success, false on failure.
  *
  */
@@ -259,15 +249,14 @@
 /** Dispatch the IRQ.
  *
- * We assume this function is only called from interrupt
- * context (i.e. that interrupts are disabled prior to
- * this call).
- *
- * This function attempts to lookup a fitting IRQ
- * structure. In case of success, return with interrupts
- * disabled and holding the respective structure.
+ * We assume this function is only called from interrupt context (i.e. that
+ * interrupts are disabled prior to this call).
+ *
+ * This function attempts to lookup a fitting IRQ structure. In case of success,
+ * return with interrupts disabled and holding the respective structure.
  *
  * @param inr Interrupt number (aka inr or irq).
  *
- * @return IRQ structure of the respective device or NULL.
+ * @return IRQ structure of the respective device
+ * @return NULL if no IRQ structure found
  *
  */
@@ -275,11 +264,8 @@
 {
 	/*
-	 * If the kernel console override is on,
-	 * then try first the kernel handlers
-	 * and eventually fall back to uspace
-	 * handlers.
+	 * If the kernel console override is on, then try first the kernel
+	 * handlers and eventually fall back to uspace handlers.
 	 *
-	 * In the usual case the uspace handlers
-	 * have precedence.
+	 * In the usual case the uspace handlers have precedence.
 	 */
 	
@@ -301,8 +287,6 @@
 /** Compute hash index for the key.
  *
- * This function computes hash index into
- * the IRQ hash table for which there
- * can be collisions between different
- * INRs.
+ * This function computes hash index into the IRQ hash table for which there can
+ * be collisions between different INRs.
  *
  * The devno is not used to compute the hash.
@@ -321,21 +305,19 @@
 /** Compare hash table element with a key.
  *
- * There are two things to note about this function.
- * First, it is used for the more complex architecture setup
- * in which there are way too many interrupt numbers (i.e. inr's)
- * to arrange the hash table so that collisions occur only
- * among same inrs of different devnos. So the explicit check
- * for inr match must be done.
- * Second, if devno is -1, the second key (i.e. devno) is not
- * used for the match and the result of the claim() function
- * is used instead.
+ * There are two things to note about this function.  First, it is used for the
+ * more complex architecture setup in which there are way too many interrupt
+ * numbers (i.e. inr's) to arrange the hash table so that collisions occur only
+ * among same inrs of different devnos. So the explicit check for inr match must
+ * be done.  Second, if devno is -1, the second key (i.e. devno) is not used for
+ * the match and the result of the claim() function is used instead.
  *
  * This function assumes interrupts are already disabled.
  *
  * @param key  Keys (i.e. inr and devno).
- * @param keys This is 2.
+ * @param keys This is 2. 
  * @param item The item to compare the key with.
  *
- * @return True on match or false otherwise.
+ * @return true on match
+ * @return false on no match
  *
  */
@@ -378,8 +360,6 @@
 /** Compute hash index for the key.
  *
- * This function computes hash index into
- * the IRQ hash table for which there
- * are no collisions between different
- * INRs.
+ * This function computes hash index into the IRQ hash table for which there are
+ * no collisions between different INRs.
  *
  * @param key The first of the keys is inr and the second is devno or -1.
@@ -396,21 +376,19 @@
 /** Compare hash table element with a key.
  *
- * There are two things to note about this function.
- * First, it is used for the less complex architecture setup
- * in which there are not too many interrupt numbers (i.e. inr's)
- * to arrange the hash table so that collisions occur only
- * among same inrs of different devnos. So the explicit check
- * for inr match is not done.
- * Second, if devno is -1, the second key (i.e. devno) is not
- * used for the match and the result of the claim() function
- * is used instead.
+ * There are two things to note about this function.  First, it is used for the
+ * less complex architecture setup in which there are not too many interrupt
+ * numbers (i.e. inr's) to arrange the hash table so that collisions occur only
+ * among same inrs of different devnos. So the explicit check for inr match is
+ * not done.  Second, if devno is -1, the second key (i.e. devno) is not used
+ * for the match and the result of the claim() function is used instead.
  *
  * This function assumes interrupts are already disabled.
  *
  * @param key  Keys (i.e. inr and devno).
- * @param keys This is 2.
+ * @param keys This is 2. 
  * @param item The item to compare the key with.
  *
- * @return True on match or false otherwise.
+ * @return true on match
+ * @return false on no match
  *
  */
