Index: uspace/lib/libc/generic/async.c
===================================================================
--- uspace/lib/libc/generic/async.c	(revision f5b4fb9e3f8394a50dce063b7a44b6e5b2ab1468)
+++ uspace/lib/libc/generic/async.c	(revision b76f2f85ffb6421f653aa078c6a01b7bfd833786)
@@ -73,5 +73,5 @@
  * 
  *
- * client_connection(icallid, *icall)
+ * my_client_connection(icallid, *icall)
  * {
  * 	if (want_refuse) {
@@ -116,5 +116,5 @@
 	link_t link;
 
-	/** Fibril waiting for this message. */
+	/** Identification of and link to the waiting fibril. */
 	fid_t fid;
 	/** If true, this fibril is currently active. */
@@ -135,4 +135,8 @@
 } amsg_t;
 
+/**
+ * Structures of this type are used to group information about a call and a
+ * message queue link.
+ */
 typedef struct {
 	link_t link;
@@ -168,11 +172,21 @@
 __thread connection_t *FIBRIL_connection;
 
-/** If true, it is forbidden to use async_req functions and all preemption is
- * disabled. */
+/**
+ * If true, it is forbidden to use async_req functions and all preemption is
+ * disabled.
+ */
 __thread int in_interrupt_handler;
 
 static void default_client_connection(ipc_callid_t callid, ipc_call_t *call);
 static void default_interrupt_received(ipc_callid_t callid, ipc_call_t *call);
+
+/**
+ * Pointer to a fibril function that will be used to handle connections.
+ */
 static async_client_conn_t client_connection = default_client_connection;
+/**
+ * Pointer to a fibril function that will be used to handle interrupt
+ * notifications.
+ */
 static async_client_conn_t interrupt_received = default_interrupt_received;
 
@@ -252,4 +266,14 @@
 /** Try to route a call to an appropriate connection fibril.
  *
+ * If the proper connection fibril is found, a message with the call is added to
+ * its message queue. If the fibril was not active, it is activated and all
+ * timeouts are unregistered.
+ *
+ * @param callid	Hash of the incoming call.
+ * @param call		Data of the incoming call.
+ *
+ * @return		Zero if the call doesn't match any connection.
+ * 			One if the call was passed to the respective connection
+ * 			fibril.
  */
 static int route_call(ipc_callid_t callid, ipc_call_t *call)
@@ -278,5 +302,5 @@
 		conn->close_callid = callid;
 	
-	/* If the call is waiting for event, run it */
+	/* If the connection fibril is waiting for an event, activate it */
 	if (!conn->wdata.active) {
 		/* If in timeout list, remove it */
@@ -315,5 +339,5 @@
 	 * GCC 4.1.1 happilly puts the rdhwr instruction in delay slot.
 	 *           I would never expect to find so many errors in 
-	 *           compiler *($&$(*&$
+	 *           a compiler *($&$(*&$
 	 */
 	conn = FIBRIL_connection; 
@@ -357,7 +381,10 @@
 }
 
-/** Fibril function that gets created on new connection
+/** Default fibril function that gets called to handle new connection.
  *
  * This function is defined as a weak symbol - to be redefined in user code.
+ *
+ * @param callid	Hash of the incoming call.
+ * @param call		Data of the incoming call.
  */
 static void default_client_connection(ipc_callid_t callid, ipc_call_t *call)
@@ -365,4 +392,10 @@
 	ipc_answer_fast(callid, ENOENT, 0, 0);
 }
+
+/** Default fibril function that gets called to handle interrupt notifications.
+ *
+ * @param callid	Hash of the incoming call.
+ * @param call		Data of the incoming call.
+ */
 static void default_interrupt_received(ipc_callid_t callid, ipc_call_t *call)
 {
@@ -371,8 +404,8 @@
 /** Wrapper for client connection fibril.
  *
- * When new connection arrives, a fibril with this implementing function is
+ * When a new connection arrives, a fibril with this implementing function is
  * created. It calls client_connection() and does the final cleanup.
  *
- * @param arg		Connection structure pointer
+ * @param arg		Connection structure pointer.
  *
  * @return		Always zero.
@@ -389,5 +422,5 @@
 	    &FIBRIL_connection->call);
 	
-	/* Remove myself from connection hash table */
+	/* Remove myself from the connection hash table */
 	futex_down(&async_futex);
 	key = FIBRIL_connection->in_phone_hash;
@@ -395,5 +428,5 @@
 	futex_up(&async_futex);
 	
-	/* Answer all remaining messages with ehangup */
+	/* Answer all remaining messages with EHANGUP */
 	while (!list_empty(&FIBRIL_connection->msg_queue)) {
 		msg = list_get_instance(FIBRIL_connection->msg_queue.next,
@@ -417,10 +450,11 @@
  * particular fibrils.
  *
- * @param in_phone_hash	Identification of the incoming connection
- * @param callid	Callid of the IPC_M_CONNECT_ME_TO packet
- * @param call		Call data of the opening packet
- * @param cfibril	Fibril function that should be called upon
- *                	opening the connection
- * @return 		New fibril id.
+ * @param in_phone_hash	Identification of the incoming connection.
+ * @param callid	Hash of the opening IPC_M_CONNECT_ME_TO call.
+ * @param call		Call data of the opening call.
+ * @param cfibril	Fibril function that should be called upon opening the
+ * 			connection.
+ *
+ * @return 		New fibril id or NULL on failure.
  */
 fid_t async_new_connection(ipcarg_t in_phone_hash, ipc_callid_t callid,
@@ -441,5 +475,5 @@
 	if (call)
 		conn->call = *call;
-	conn->wdata.active = 1; /* We will activate it asap */
+	conn->wdata.active = 1;	/* We will activate the fibril ASAP */
 	conn->cfibril = cfibril;
 
@@ -450,5 +484,5 @@
 		return NULL;
 	}
-	/* Add connection to hash table */
+	/* Add connection to the connection hash table */
 	key = conn->in_phone_hash;
 	futex_down(&async_futex);
@@ -461,5 +495,12 @@
 }
 
-/** Handle a call that was received. */
+/** Handle a call that was received.
+ *
+ * If the call has the IPC_M_CONNECT_ME_TO method, a new connection is created.
+ * Otherwise the call is routed to its connection fibril.
+ *
+ * @param callid	Hash of the incoming call.
+ * @param call		Data of the incoming call.
+ */
 static void handle_call(ipc_callid_t callid, ipc_call_t *call)
 {
@@ -480,5 +521,5 @@
 	}
 
-	/* Try to route call through connection tables */
+	/* Try to route the call through the connection hash table */
 	if (route_call(callid, call))
 		return;
@@ -495,5 +536,5 @@
 	link_t *cur;
 
-	gettimeofday(&tv,NULL);
+	gettimeofday(&tv, NULL);
 	futex_down(&async_futex);
 
@@ -507,6 +548,7 @@
 		waiter->inlist = 0;
 		waiter->timedout = 1;
-		/* Redundant condition? The fibril should not
-		 * be active when it gets here.
+		/*
+ 		 * Redundant condition?
+ 		 * The fibril should not be active when it gets here.
 		 */
 		if (!waiter->active) {
@@ -519,5 +561,8 @@
 }
 
-/** Endless loop dispatching incoming calls and answers */
+/** Endless loop dispatching incoming calls and answers.
+ *
+ * @return		Never returns.
+ */
 static int async_manager_worker(void)
 {
@@ -531,6 +576,7 @@
 		if (fibril_schedule_next_adv(FIBRIL_FROM_MANAGER)) {
 			futex_up(&async_futex); 
-			/* async_futex is always held
-			 * when entering manager fibril
+			/*
+			 * async_futex is always held when entering a manager
+			 * fibril.
 			 */
 			continue;
@@ -568,14 +614,18 @@
 }
 
-/** Function to start async_manager as a standalone fibril. 
+/** Function to start async_manager as a standalone fibril.
  * 
- * When more kernel threads are used, one async manager should
- * exist per thread.
+ * When more kernel threads are used, one async manager should exist per thread.
+ *
+ * @param arg		Unused.
+ *
+ * @return		Never returns.
  */
 static int async_manager_fibril(void *arg)
 {
 	futex_up(&async_futex);
-	/* async_futex is always locked when entering
-	 * manager */
+	/*
+	 * async_futex is always locked when entering manager
+	 */
 	async_manager_worker();
 	
@@ -583,5 +633,5 @@
 }
 
-/** Add one manager to manager list */
+/** Add one manager to manager list. */
 void async_create_manager(void)
 {
@@ -598,5 +648,8 @@
 }
 
-/** Initialize internal structures needed for async manager */
+/** Initialize the async framework.
+ *
+ * @return		Zero on success or an error code.
+ */
 int _async_init(void)
 {
@@ -610,7 +663,14 @@
 }
 
-/** IPC handler for messages in async framework
- *
- * Notify the fibril which is waiting for this message, that it arrived
+/** Reply received callback.
+ *
+ * This function is called whenever a reply for an asynchronous message sent out
+ * by the asynchronous framework is received.
+ *
+ * Notify the fibril which is waiting for this message that it has arrived.
+ *
+ * @param private	Pointer to the asynchronous message record.
+ * @param retval	Value returned in the answer.
+ * @param data		Call data of the answer.
  */
 static void reply_received(void *private, int retval, ipc_call_t *data)
@@ -621,7 +681,5 @@
 
 	futex_down(&async_futex);
-	/* Copy data after futex_down, just in case the
-	 * call was detached 
-	 */
+	/* Copy data after futex_down, just in case the call was detached */
 	if (msg->dataptr)
 		*msg->dataptr = *data; 
@@ -632,5 +690,5 @@
 		list_remove(&msg->wdata.link);
 	msg->done = 1;
-	if (! msg->wdata.active) {
+	if (!msg->wdata.active) {
 		msg->wdata.active = 1;
 		fibril_add_ready(msg->wdata.fid);
@@ -639,8 +697,17 @@
 }
 
-/** Send message and return id of the sent message
- *
- * The return value can be used as input for async_wait() to wait
- * for completion.
+/** Send message and return id of the sent message.
+ *
+ * The return value can be used as input for async_wait() to wait for
+ * completion.
+ *
+ * @param phoneid	Handle of the phone that will be used for the send.
+ * @param method	Service-defined method.
+ * @param arg1		Service-defined payload argument.
+ * @param arg2		Service-defined payload argument.
+ * @param dataptr	If non-NULL, storage where the reply data will be
+ * 			stored.
+ *
+ * @return		Hash of the sent message.
  */
 aid_t async_send_2(int phoneid, ipcarg_t method, ipcarg_t arg1, ipcarg_t arg2,
@@ -659,6 +726,7 @@
 	msg->dataptr = dataptr;
 
-	msg->wdata.active = 1; /* We may sleep in next method, but it
-				* will use it's own mechanism */
+	/* We may sleep in the next method, but it will use its own mechanism */
+	msg->wdata.active = 1; 
+				
 	ipc_call_async_2(phoneid, method, arg1, arg2, msg, reply_received, 1);
 
@@ -668,6 +736,16 @@
 /** Send message and return id of the sent message
  *
- * The return value can be used as input for async_wait() to wait
- * for completion.
+ * The return value can be used as input for async_wait() to wait for
+ * completion.
+ *
+ * @param phoneid	Handle of the phone that will be used for the send.
+ * @param method	Service-defined method.
+ * @param arg1		Service-defined payload argument.
+ * @param arg2		Service-defined payload argument.
+ * @param arg3		Service-defined payload argument.
+ * @param dataptr	If non-NULL, storage where the reply data will be
+ * 			stored.
+ *
+ * @return		Hash of the sent message.
  */
 aid_t async_send_3(int phoneid, ipcarg_t method, ipcarg_t arg1, ipcarg_t arg2,
@@ -677,5 +755,6 @@
 
 	if (in_interrupt_handler) {
-		printf("Cannot send asynchronous request in interrupt handler.\n");
+		printf("Cannot send asynchronous request in interrupt "
+		    "handler.\n");
 		_exit(1);
 	}
@@ -685,6 +764,7 @@
 	msg->dataptr = dataptr;
 
-	msg->wdata.active = 1; /* We may sleep in next method, but it
-				* will use it's own mechanism */
+	/* We may sleep in next method, but it will use its own mechanism */
+	msg->wdata.active = 1; 
+				
 	ipc_call_async_3(phoneid, method, arg1, arg2, arg3, msg, reply_received,
 	    1);
@@ -693,9 +773,9 @@
 }
 
-/** Wait for a message sent by async framework
- *
- * @param amsgid	Message ID to wait for
- * @param retval	Pointer to variable where will be stored retval of the
- *			answered message. If NULL, it is ignored.
+/** Wait for a message sent by the async framework.
+ *
+ * @param amsgid	Hash of the message to wait for.
+ * @param retval	Pointer to storage where the retval of the answer will
+ * 			be stored.
  */
 void async_wait_for(aid_t amsgid, ipcarg_t *retval)
@@ -712,5 +792,5 @@
 	msg->wdata.active = 0;
 	msg->wdata.inlist = 0;
-	/* Leave locked async_futex when entering this function */
+	/* Leave the async_futex locked when entering this function */
 	fibril_schedule_next_adv(FIBRIL_TO_MANAGER);
 	/* futex is up automatically after fibril_schedule_next...*/
@@ -721,12 +801,12 @@
 }
 
-/** Wait for a message sent by async framework with timeout
- *
- * @param amsgid Message ID to wait for
- * @param retval Pointer to variable where will be stored retval
- *               of the answered message. If NULL, it is ignored.
- * @param timeout Timeout in usecs
- * @return 0 on success, ETIMEOUT if timeout expired
- *
+/** Wait for a message sent by the async framework, timeout variant.
+ *
+ * @param amsgid	Hash of the message to wait for.
+ * @param retval	Pointer to storage where the retval of the answer will
+ * 			be stored.
+ * @param timeout	Timeout in microseconds.
+ *
+ * @return		Zero on success, ETIMEOUT if the timeout has expired.
  */
 int async_wait_timeout(aid_t amsgid, ipcarg_t *retval, suseconds_t timeout)
@@ -751,5 +831,5 @@
 	insert_timeout(&msg->wdata);
 
-	/* Leave locked async_futex when entering this function */
+	/* Leave the async_futex locked when entering this function */
 	fibril_schedule_next_adv(FIBRIL_TO_MANAGER);
 	/* futex is up automatically after fibril_schedule_next...*/
@@ -766,7 +846,9 @@
 }
 
-/** Wait specified time, but in the meantime handle incoming events
- *
- * @param timeout Time in microseconds to wait
+/** Wait for specified time.
+ *
+ * The current fibril is suspended but the thread continues to execute.
+ *
+ * @param timeout	Duration of the wait in microseconds.
  */
 void async_usleep(suseconds_t timeout)
@@ -791,5 +873,5 @@
 	futex_down(&async_futex);
 	insert_timeout(&msg->wdata);
-	/* Leave locked the async_futex when entering this function */
+	/* Leave the async_futex locked when entering this function */
 	fibril_schedule_next_adv(FIBRIL_TO_MANAGER);
 	/* futex is up automatically after fibril_schedule_next_adv()...*/
@@ -797,7 +879,7 @@
 }
 
-/** Set function that is called when IPC_M_CONNECT_ME_TO is received.
- *
- * @param conn Function that will form a new fibril.
+/** Setter for client_connection function pointer.
+ *
+ * @param conn		Function that will implement a new connection fibril.
  */
 void async_set_client_connection(async_client_conn_t conn)
@@ -805,4 +887,10 @@
 	client_connection = conn;
 }
+
+/** Setter for interrupt_received function pointer.
+ *
+ * @param conn		Function that will implement a new interrupt
+ *			notification fibril.
+ */
 void async_set_interrupt_received(async_client_conn_t conn)
 {
@@ -826,2 +914,3 @@
 /** @}
  */
+
Index: uspace/lib/libc/generic/ipc.c
===================================================================
--- uspace/lib/libc/generic/ipc.c	(revision f5b4fb9e3f8394a50dce063b7a44b6e5b2ab1468)
+++ uspace/lib/libc/generic/ipc.c	(revision b76f2f85ffb6421f653aa078c6a01b7bfd833786)
@@ -52,6 +52,7 @@
 #include <fibril.h>
 
-/** Structure used for keeping track of sent asynchronous calls and queing
- * unsent calls.
+/**
+ * Structures of this type are used for keeping track of sent asynchronous calls
+ * and queing unsent calls.
  */
 typedef struct {