Index: src/synch/rwlock.c
===================================================================
--- src/synch/rwlock.c	(revision ac4177ca326ab1e168871eca101321c21ba8c478)
+++ src/synch/rwlock.c	(revision f02436c853f7391325b4f31e29a566f824c618fb)
@@ -51,10 +51,9 @@
  */
  
-#include <synch/synch.h>
 #include <synch/rwlock.h>
 #include <synch/spinlock.h>
 #include <synch/mutex.h>
 #include <synch/waitq.h>
-
+#include <synch/synch.h>
 #include <list.h>
 #include <typedefs.h>
@@ -70,4 +69,10 @@
 static void release_spinlock(void *arg);
 
+/** Initialize reader/writer lock
+ *
+ * Initialize reader/writer lock.
+ *
+ * @param rwl Reader/Writer lock.
+ */
 void rwlock_initialize(rwlock_t *rwl) {
 	spinlock_initialize(&rwl->lock);
@@ -76,4 +81,18 @@
 }
 
+/** Acquire reader/writer lock for reading
+ *
+ * Acquire reader/writer lock for reading.
+ * Timeout and willingness to block may be specified.
+ *
+ * @param rwl Reader/Writer lock.
+ * @param usec Timeout in microseconds.
+ * @param trylock Switches between blocking and non-blocking mode.
+ *
+ * For exact description of possible combinations of
+ * 'usec' and 'trylock', see comment for waitq_sleep_timeout().
+ *
+ * @return See comment for waitq_sleep_timeout().
+ */
 int _rwlock_write_lock_timeout(rwlock_t *rwl, __u32 usec, int trylock)
 {
@@ -116,4 +135,18 @@
 }
 
+/** Acquire reader/writer lock for writing
+ *
+ * Acquire reader/writer lock for writing.
+ * Timeout and willingness to block may be specified.
+ *
+ * @param rwl Reader/Writer lock.
+ * @param usec Timeout in microseconds.
+ * @param trylock Switches between blocking and non-blocking mode.
+ *
+ * For exact description of possible combinations of
+ * 'usec' and 'trylock', see comment for waitq_sleep_timeout().
+ *
+ * @return See comment for waitq_sleep_timeout().
+ */
 int _rwlock_read_lock_timeout(rwlock_t *rwl, __u32 usec, int trylock)
 {
@@ -209,4 +242,12 @@
 }
 
+/** Release reader/writer lock held by writer
+ *
+ * Release reader/writer lock held by writer.
+ * Handoff reader/writer lock ownership directly
+ * to waiting readers or a writer.
+ *
+ * @param rwl Reader/Writer lock.
+ */
 void rwlock_write_unlock(rwlock_t *rwl)
 {
@@ -221,4 +262,13 @@
 }
 
+/** Release reader/writer lock held by reader
+ *
+ * Release reader/writer lock held by reader.
+ * Handoff reader/writer lock ownership directly
+ * to a waiting writer or don't do anything if more
+ * readers poses the lock.
+ *
+ * @param rwl Reader/Writer lock.
+ */
 void rwlock_read_unlock(rwlock_t *rwl)
 {
@@ -234,9 +284,15 @@
 
 
-/*
+/** Direct handoff
+ *
+ * Direct handoff of reader/writer lock ownership
+ * to waiting readers or a writer.
+ *
  * Must be called with rwl->lock locked.
  * Must be called with cpu_priority_high'ed.
- */
-/*
+ *
+ * @param rwl Reader/Writer lock.
+ * @param readers_only See the description below.
+ *
  * If readers_only is false: (unlock scenario)
  * Let the first sleeper on 'exclusive' mutex in, no matter
@@ -306,4 +362,11 @@
 }
 
+/** Release spinlock callback
+ *
+ * This is a callback function invoked from the scheduler.
+ * The callback is registered in _rwlock_read_lock_timeout().
+ *
+ * @param arg Spinlock.
+ */
 void release_spinlock(void *arg)
 {