Index: uspace/lib/nettl/src/amap.c
===================================================================
--- uspace/lib/nettl/src/amap.c	(revision c3f7d37086023df6580ccd4691db2d699c80ccf6)
+++ uspace/lib/nettl/src/amap.c	(revision abf2dfde554829308532f8d95a182c0db6fcf54c)
@@ -36,4 +36,16 @@
  * Manages allocations of endpoints / endpoint pairs (corresponding to
  * UDP associations, TCP listeners and TCP connections)
+ *
+ * An association map contains different types of entries, based on which
+ * set of attributes (key) they specify. In order from most specific to the
+ * least specific one:
+ *
+ *  - repla (remote endpoint, local address)
+ *  - laddr (local address)
+ *  - llink (local link)
+ *  - unspec (unspecified)
+ *
+ * In the unspecified case only the local port is known and the entry matches
+ * all remote and local addresses.
  */
 
@@ -47,4 +59,9 @@
 #include <stdlib.h>
 
+/** Create association map.
+ *
+ * @param rmap Place to store pointer to new association map
+ * @return EOk on success, ENOMEM if out of memory
+ */
 int amap_create(amap_t **rmap)
 {
@@ -73,4 +90,8 @@
 }
 
+/** Destroy association map.
+ *
+ * @param map Association map
+ */
 void amap_destroy(amap_t *map)
 {
@@ -79,5 +100,15 @@
 }
 
-/** Find exact repla */
+/** Find exact repla.
+ *
+ * Find repla (remote endpoint, local address) entry by exact match.
+ *
+ * @param map Association map
+ * @param rep Remote endpoint
+ * @param la  Local address
+ * @param rrepla Place to store pointer to repla
+ *
+ * @return EOK on success, ENOENT if not found
+ */
 static int amap_repla_find(amap_t *map, inet_ep_t *rep, inet_addr_t *la,
     amap_repla_t **rrepla)
@@ -113,4 +144,15 @@
 }
 
+/** Insert repla.
+ *
+ * Insert new repla (remote endpoint, local address) entry to association map.
+ *
+ * @param amap   Association map
+ * @param rep    Remote endpoint
+ * @param la     Local address
+ * @param rrepla Place to store pointer to new repla
+ *
+ * @return EOK on success, ENOMEM if out of memory
+ */
 static int amap_repla_insert(amap_t *map, inet_ep_t *rep, inet_addr_t *la,
     amap_repla_t **rrepla)
@@ -139,4 +181,11 @@
 }
 
+/** Remove repla from association map.
+ *
+ * Remove repla (remote endpoint, local address) from association map.
+ *
+ * @param map   Association map
+ * @param repla Repla
+ */
 static void amap_repla_remove(amap_t *map, amap_repla_t *repla)
 {
@@ -146,5 +195,14 @@
 }
 
-/** Find exact laddr */
+/** Find exact laddr.
+ *
+ * Find laddr (local address) entry by exact match.
+ *
+ * @param map    Association map
+ * @param addr   Address
+ * @param rladdr Place to store pointer to laddr entry
+ *
+ * @return EOK on success, ENOENT if not found.
+ */
 static int amap_laddr_find(amap_t *map, inet_addr_t *addr,
     amap_laddr_t **rladdr)
@@ -161,4 +219,13 @@
 }
 
+/** Insert laddr.
+ *
+ * Insert new laddr (local address) entry to association map.
+ *
+ * @param addr   Local address
+ * @param rladdr Place to store pointer to new laddr
+ *
+ * @return EOK on success, ENOMEM if out of memory
+ */
 static int amap_laddr_insert(amap_t *map, inet_addr_t *addr,
     amap_laddr_t **rladdr)
@@ -186,4 +253,11 @@
 }
 
+/** Remove laddr from association map.
+ *
+ * Remove laddr (local address) entry from association map.
+ *
+ * @param map   Association map
+ * @param laddr Laddr entry
+ */
 static void amap_laddr_remove(amap_t *map, amap_laddr_t *laddr)
 {
@@ -193,5 +267,14 @@
 }
 
-/** Find exact llink */
+/** Find exact llink.
+ *
+ * Find llink (local link) entry by exact match.
+ *
+ * @param map     Association map
+ * @param link_id Local link ID
+ * @param rllink  Place to store pointer to llink entry
+ *
+ * @return EOK on success, ENOENT if not found.
+ */
 static int amap_llink_find(amap_t *map, sysarg_t link_id,
     amap_llink_t **rllink)
@@ -208,4 +291,13 @@
 }
 
+/** Insert llink.
+ *
+ * Insert new llink (local link) entry to association map.
+ *
+ * @param link_id Local link
+ * @param rllink  Place to store pointer to new llink
+ *
+ * @return EOK on success, ENOMEM if out of memory
+ */
 static int amap_llink_insert(amap_t *map, sysarg_t link_id,
     amap_llink_t **rllink)
@@ -233,4 +325,11 @@
 }
 
+/** Remove llink from association map.
+ *
+ * Remove llink (local link) entry from association map.
+ *
+ * @param map   Association map
+ * @param llink Llink entry
+ */
 static void amap_llink_remove(amap_t *map, amap_llink_t *llink)
 {
@@ -240,4 +339,17 @@
 }
 
+/** Insert endpoint pair into map with repla as key.
+ *
+ * If local port number is not specified, it is allocated.
+ *
+ * @param map Association map
+ * @param epp Endpoint pair, possibly with local port inet_port_any
+ * @param arg arg User value
+ * @param flags Flags
+ * @param aepp Place to store actual endpoint pair, possibly with allocated port
+ *
+ * @return EOK on success, EEXISTS if conflicting epp exists,
+ *         ENOMEM if out of memory
+ */
 static int amap_insert_repla(amap_t *map, inet_ep2_t *epp, void *arg,
     amap_flags_t flags, inet_ep2_t *aepp)
@@ -272,4 +384,17 @@
 }
 
+/** Insert endpoint pair into map with laddr as key.
+ *
+ * If local port number is not specified, it is allocated.
+ *
+ * @param map Association map
+ * @param epp Endpoint pair, possibly with local port inet_port_any
+ * @param arg arg User value
+ * @param flags Flags
+ * @param aepp Place to store actual endpoint pair, possibly with allocated port
+ *
+ * @return EOK on success, EEXISTS if conflicting epp exists,
+ *         ENOMEM if out of memory
+ */
 static int amap_insert_laddr(amap_t *map, inet_ep2_t *epp, void *arg,
     amap_flags_t flags, inet_ep2_t *aepp)
@@ -303,4 +428,17 @@
 }
 
+/** Insert endpoint pair into map with llink as key.
+ *
+ * If local port number is not specified, it is allocated.
+ *
+ * @param map Association map
+ * @param epp Endpoint pair, possibly with local port inet_port_any
+ * @param arg arg User value
+ * @param flags Flags
+ * @param aepp Place to store actual endpoint pair, possibly with allocated port
+ *
+ * @return EOK on success, EEXISTS if conflicting epp exists,
+ *         ENOMEM if out of memory
+ */
 static int amap_insert_llink(amap_t *map, inet_ep2_t *epp, void *arg,
     amap_flags_t flags, inet_ep2_t *aepp)
@@ -334,4 +472,17 @@
 }
 
+/** Insert endpoint pair into map with unspec as key.
+ *
+ * If local port number is not specified, it is allocated.
+ *
+ * @param map Association map
+ * @param epp Endpoint pair, possibly with local port inet_port_any
+ * @param arg arg User value
+ * @param flags Flags
+ * @param aepp Place to store actual endpoint pair, possibly with allocated port
+ *
+ * @return EOK on success, EEXISTS if conflicting epp exists,
+ *         ENOMEM if out of memory
+ */
 static int amap_insert_unspec(amap_t *map, inet_ep2_t *epp, void *arg,
     amap_flags_t flags, inet_ep2_t *aepp)
@@ -417,4 +568,12 @@
 }
 
+/** Remove endpoint pair using repla as key from map.
+ *
+ * The endpoint pair must be present in the map, otherwise behavior
+ * is unspecified.
+ *
+ * @param map Association map
+ * @param epp Endpoint pair
+ */
 static void amap_remove_repla(amap_t *map, inet_ep2_t *epp)
 {
@@ -434,4 +593,12 @@
 }
 
+/** Remove endpoint pair using laddr as key from map.
+ *
+ * The endpoint pair must be present in the map, otherwise behavior
+ * is unspecified.
+ *
+ * @param map Association map
+ * @param epp Endpoint pair
+ */
 static void amap_remove_laddr(amap_t *map, inet_ep2_t *epp)
 {
@@ -451,4 +618,12 @@
 }
 
+/** Remove endpoint pair using llink as key from map.
+ *
+ * The endpoint pair must be present in the map, otherwise behavior
+ * is unspecified.
+ *
+ * @param map Association map
+ * @param epp Endpoint pair
+ */
 static void amap_remove_llink(amap_t *map, inet_ep2_t *epp)
 {
@@ -468,4 +643,12 @@
 }
 
+/** Remove endpoint pair using unspec as key from map.
+ *
+ * The endpoint pair must be present in the map, otherwise behavior
+ * is unspecified.
+ *
+ * @param map Association map
+ * @param epp Endpoint pair
+ */
 static void amap_remove_unspec(amap_t *map, inet_ep2_t *epp)
 {
@@ -473,4 +656,12 @@
 }
 
+/** Remove endpoint pair from map.
+ *
+ * The endpoint pair must be present in the map, otherwise behavior
+ * is unspecified.
+ *
+ * @param map Association map
+ * @param epp Endpoint pair
+ */
 void amap_remove(amap_t *map, inet_ep2_t *epp)
 {
