Documentation updates

Mostly killing doxygen warnings, some doc updates to caching

12 files changed, 198 insertions, 74 deletions

diff --git a/include/netlink/cache-api.h b/include/netlink/cache-api.h
index 22fc449..efae2ed 100644
--- a/include/netlink/cache-api.h
+++ b/include/netlink/cache-api.h
@@ -151,21 +151,40 @@ struct nl_af_group
 
 #define END_OF_GROUP_LIST AF_UNSPEC, 0
 
+/**
+ * Parser parameters
+ *
+ * This structure is used to configure what kind of parser to use
+ * when parsing netlink messages to create objects.
+ */
 struct nl_parser_param
 {
+	/** Function to parse netlink messages into objects */
 	int             (*pp_cb)(struct nl_object *, struct nl_parser_param *);
+
+	/** Arbitary argument to be passed to the parser */
 	void *            pp_arg;
 };
 
 /**
  * Cache Operations
+ *
+ * This structure defines the characterstics of a cache type. It contains
+ * pointers to functions which implement the specifics of the object type
+ * the cache can hold.
  */
 struct nl_cache_ops
 {
+	/** Name of cache type (must be unique) */
 	char  *			co_name;
 
+	/** Size of family specific netlink header */
 	int			co_hdrsize;
+
+	/** Netlink protocol */
 	int			co_protocol;
+
+	/** Group definition */
 	struct nl_af_group *	co_groups;
 	
 	/**
@@ -182,11 +201,16 @@ struct nl_cache_ops
 	int   (*co_msg_parser)(struct nl_cache_ops *, struct sockaddr_nl *,
 			       struct nlmsghdr *, struct nl_parser_param *);
 
+	/** Object operations */
 	struct nl_object_ops *	co_obj_ops;
 
+	/** Internal, do not touch! */
 	struct nl_cache_ops *co_next;
+
 	struct nl_cache *co_major_cache;
 	struct genl_ops *	co_genl;
+
+	/* Message type definition */
 	struct nl_msgtype	co_msgtypes[];
 };
 
diff --git a/lib/cache.c b/lib/cache.c
index 601dadc..ece354c 100644
--- a/lib/cache.c
+++ b/lib/cache.c
@@ -160,15 +160,18 @@ struct nl_object *nl_cache_get_prev(struct nl_object *obj)
 /** @} */
 
 /**
- * @name Cache Creation/Deletion
+ * @name Cache Allocation/Deletion
  * @{
  */
 
 /**
- * Allocate an empty cache
- * @arg ops		cache operations to base the cache on
- * 
- * @return A newly allocated and initialized cache.
+ * Allocate new cache
+ * @arg ops		Cache operations
+ *
+ * Allocate and initialize a new cache based on the cache operations
+ * provided.
+ *
+ * @return Allocated cache or NULL if allocation failed.
  */
 struct nl_cache *nl_cache_alloc(struct nl_cache_ops *ops)
 {
@@ -186,6 +189,22 @@ struct nl_cache *nl_cache_alloc(struct nl_cache_ops *ops)
 	return cache;
 }
 
+/**
+ * Allocate new cache and fill it
+ * @arg ops		Cache operations
+ * @arg sock		Netlink socket
+ * @arg result		Result pointer
+ *
+ * Allocate new cache and fill it. Equivalent to calling:
+ * @code
+ * cache = nl_cache_alloc(ops);
+ * nl_cache_refill(sock, cache);
+ * @endcode
+ *
+ * @see nl_cache_alloc
+ *
+ * @return 0 on success or a negative error code.
+ */
 int nl_cache_alloc_and_fill(struct nl_cache_ops *ops, struct nl_sock *sock,
 			    struct nl_cache **result)
 {
@@ -205,9 +224,17 @@ int nl_cache_alloc_and_fill(struct nl_cache_ops *ops, struct nl_sock *sock,
 }
 
 /**
- * Allocate an empty cache based on type name
+ * Allocate new cache based on type name
  * @arg kind		Name of cache type
- * @return A newly allocated and initialized cache.
+ * @arg result		Result pointer
+ *
+ * Lookup cache ops via nl_cache_ops_lookup() and allocate the cache
+ * by calling nl_cache_alloc(). Stores the allocated cache in the
+ * result pointer provided.
+ *
+ * @see nl_cache_alloc
+ *
+ * @return 0 on success or a negative error code.
  */
 int nl_cache_alloc_name(const char *kind, struct nl_cache **result)
 {
@@ -226,9 +253,18 @@ int nl_cache_alloc_name(const char *kind, struct nl_cache **result)
 }
 
 /**
- * Allocate a new cache containing a subset of a cache
- * @arg orig		Original cache to be based on
- * @arg filter		Filter defining the subset to be filled into new cache
+ * Allocate new cache containing a subset of an existing cache
+ * @arg orig		Original cache to base new cache on
+ * @arg filter		Filter defining the subset to be filled into the new cache
+ *
+ * Allocates a new cache matching the type of the cache specified by
+ * \p orig. Iterates over the \p orig cache applying the specified
+ * \p filter and copies all objects that match to the new cache.
+ *
+ * The copied objects are clones but do not contain a reference to each
+ * other. Later modifications to objects in the original cache will
+ * not affect objects in the new cache.
+ *
  * @return A newly allocated cache or NULL.
  */
 struct nl_cache *nl_cache_subset(struct nl_cache *orig,
@@ -258,10 +294,15 @@ struct nl_cache *nl_cache_subset(struct nl_cache *orig,
 }
 
 /**
- * Clear a cache.
- * @arg cache		cache to clear
+ * Remove all objects of a cache.
+ * @arg cache		Cache to clear
  *
- * Removes all elements of a cache.
+ * The objects are unliked/removed from the cache by calling
+ * nl_cache_remove() on each object in the cache. If any of the objects
+ * to not contain any further references to them, those objects will
+ * be freed.
+ *
+ * Unlike with nl_cache_free(), the cache is not freed just emptied.
  */
 void nl_cache_clear(struct nl_cache *cache)
 {
@@ -277,9 +318,10 @@ void nl_cache_clear(struct nl_cache *cache)
  * Free a cache.
  * @arg cache		Cache to free.
  *
- * Removes all elements of a cache and frees all memory.
+ * Calls nl_cache_clear() to remove all objects associated with the
+ * cache and frees the cache afterwards.
  *
- * @note Use this function if you are working with allocated caches.
+ * @see nl_cache_clear()
  */
 void nl_cache_free(struct nl_cache *cache)
 {
@@ -312,12 +354,24 @@ static int __cache_add(struct nl_cache *cache, struct nl_object *obj)
 }
 
 /**
- * Add object to a cache.
- * @arg cache		Cache to add object to
+ * Add object to cache.
+ * @arg cache		Cache
  * @arg obj		Object to be added to the cache
  *
- * Adds the given object to the specified cache. The object is cloned
- * if it has been added to another cache already.
+ * Adds the object \p obj to the specified \p cache. In case the object
+ * is already associated with another cache, the object is cloned before
+ * adding it to the cache. In this case, the sole reference to the object
+ * will be the one of the cache. Therefore clearing/freeing the cache
+ * will result in the object being freed again.
+ *
+ * If the object has not been associated with a cache yet, the reference
+ * counter of the object is incremented to account for the additional
+ * reference.
+ *
+ * The type of the object and cache must match, otherwise an error is
+ * returned (-NLE_OBJ_MISMATCH).
+ *
+ * @see nl_cache_move()
  *
  * @return 0 or a negative error code.
  */
@@ -345,8 +399,16 @@ int nl_cache_add(struct nl_cache *cache, struct nl_object *obj)
  * @arg cache		Cache to move object to.
  * @arg obj		Object subject to be moved
  *
- * Removes the given object from its associated cache if needed
- * and adds it to the new cache.
+ * Removes the the specified object \p obj from its associated cache
+ * and moves it to another cache.
+ *
+ * If the object is not associated with a cache, the function behaves
+ * just like nl_cache_add().
+ *
+ * The type of the object and cache must match, otherwise an error is
+ * returned (-NLE_OBJ_MISMATCH).
+ *
+ * @see nl_cache_add()
  *
  * @return 0 on success or a negative error code.
  */
@@ -368,12 +430,14 @@ int nl_cache_move(struct nl_cache *cache, struct nl_object *obj)
 }
 
 /**
- * Removes an object from a cache.
- * @arg obj		Object to remove from its cache
+ * Remove object from cache.
+ * @arg obj		Object to remove from cache
  *
- * Removes the object \c obj from the cache it is assigned to, since
- * an object can only be assigned to one cache at a time, the cache
- * must ne be passed along with it.
+ * Removes the object \c obj from the cache it is associated with. The
+ * reference counter of the object will be decremented. If the reference
+ * to the object was the only one remaining, the object will be freed.
+ *
+ * If no cache is associated with the object, this function is a NOP.
  */
 void nl_cache_remove(struct nl_object *obj)
 {
@@ -391,33 +455,6 @@ void nl_cache_remove(struct nl_object *obj)
 	       obj, cache, nl_cache_name(cache));
 }
 
-/**
- * Search for an object in a cache
- * @arg cache		Cache to search in.
- * @arg needle		Object to look for.
- *
- * Iterates over the cache and looks for an object with identical
- * identifiers as the needle.
- *
- * @return Reference to object or NULL if not found.
- * @note The returned object must be returned via nl_object_put().
- */
-struct nl_object *nl_cache_search(struct nl_cache *cache,
-				  struct nl_object *needle)
-{
-	struct nl_object *obj;
-
-	nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
-		if (nl_object_identical(obj, needle)) {
-			nl_object_get(obj);
-			return obj;
-		}
-	}
-
-	return NULL;
-}
-
-
 /** @} */
 
 /**
@@ -426,15 +463,28 @@ struct nl_object *nl_cache_search(struct nl_cache *cache,
  */
 
 /**
- * Request a full dump from the kernel to fill a cache
+ * Invoke the request-update operation
  * @arg sk		Netlink socket.
- * @arg cache		Cache subjected to be filled.
+ * @arg cache		Cache
+ *
+ * This function causes the \e request-update function of the cache
+ * operations to be invoked. This usually causes a dump request to
+ * be sent over the netlink socket which triggers the kernel to dump
+ * all objects of a specific type to be dumped onto the netlink
+ * socket for pickup.
  *
- * Send a dumping request to the kernel causing it to dump all objects
- * related to the specified cache to the netlink socket.
+ * The behaviour of this function depends on the implemenation of
+ * the \e request_update function of each individual type of cache.
  *
- * Use nl_cache_pickup() to read the objects from the socket and fill them
- * into a cache.
+ * This function will not have any effects on the cache (unless the
+ * request_update implementation of the cache operations does so).
+ *
+ * Use nl_cache_pickup() to pick-up (read) the objects from the socket
+ * and fill them into the cache.
+ *
+ * @see nl_cache_pickup(), nl_cache_resync()
+ *
+ * @return 0 on success or a negative error code.
  */
 int nl_cache_request_full_dump(struct nl_sock *sk, struct nl_cache *cache)
 {
@@ -461,6 +511,12 @@ static int update_msg_parser(struct nl_msg *msg, void *arg)
 }
 /** @endcond */
 
+/**
+ * Pick-up a netlink request-update with your own parser
+ * @arg sk		Netlink socket
+ * @arg cache		Cache
+ * @arg param		Parser parameters
+ */
 int __cache_pickup(struct nl_sock *sk, struct nl_cache *cache,
 		   struct nl_parser_param *param)
 {
@@ -707,8 +763,41 @@ int nl_cache_refill(struct nl_sock *sk, struct nl_cache *cache)
  */
 
 /**
- * Mark all objects in a cache
- * @arg cache		Cache to mark all objects in
+ * Search object in cache
+ * @arg cache		Cache
+ * @arg needle		Object to look for.
+ *
+ * Searches the cache for an object which matches the object \p needle.
+ * The function nl_object_identical() is used to determine if the
+ * objects match. If a matching object is found, the reference counter
+ * is incremented and the object is returned.
+ * 
+ * Therefore, if an object is returned, the reference to the object
+ * must be returned by calling nl_object_put() after usage.
+ *
+ * @return Reference to object or NULL if not found.
+ */
+struct nl_object *nl_cache_search(struct nl_cache *cache,
+				  struct nl_object *needle)
+{
+	struct nl_object *obj;
+
+	nl_list_for_each_entry(obj, &cache->c_items, ce_list) {
+		if (nl_object_identical(obj, needle)) {
+			nl_object_get(obj);
+			return obj;
+		}
+	}
+
+	return NULL;
+}
+
+/**
+ * Mark all objects of a cache
+ * @arg cache		Cache
+ *
+ * Marks all objects of a cache by calling nl_object_mark() on each
+ * object associated with the cache.
  */
 void nl_cache_mark_all(struct nl_cache *cache)
 {
diff --git a/lib/cache_mngr.c b/lib/cache_mngr.c
index 81052aa..cfa676b 100644
--- a/lib/cache_mngr.c
+++ b/lib/cache_mngr.c
@@ -143,8 +143,9 @@ found:
  * @arg sk		Netlink socket.
  * @arg protocol	Netlink Protocol this manager is used for
  * @arg flags		Flags
+ * @arg result		Result pointer
  *
- * @return Newly allocated cache manager or NULL on failure.
+ * @return 0 on success or a negative error code.
  */
 int nl_cache_mngr_alloc(struct nl_sock *sk, int protocol, int flags,
 			struct nl_cache_mngr **result)
@@ -196,6 +197,7 @@ errout:
  * @arg mngr		Cache manager.
  * @arg name		Name of cache to keep track of
  * @arg cb		Function to be called upon changes.
+ * @arg data		Argument passed on to change callback
  * @arg result		Pointer to store added cache.
  *
  * Allocates a new cache of the specified type and adds it to the manager.
diff --git a/lib/fib_lookup/lookup.c b/lib/fib_lookup/lookup.c
index ce9c027..61984c7 100644
--- a/lib/fib_lookup/lookup.c
+++ b/lib/fib_lookup/lookup.c
@@ -192,6 +192,7 @@ struct nl_cache *flnl_result_alloc_cache(void)
  * Builds a netlink request message to do a lookup
  * @arg req		Requested match.
  * @arg flags		additional netlink message flags
+ * @arg result		Result pointer
  *
  * Builds a new netlink message requesting a change of link attributes.
  * The netlink message header isn't fully equipped with all relevant
@@ -201,7 +202,7 @@ struct nl_cache *flnl_result_alloc_cache(void)
  * and \a tmpl must contain the attributes to be changed set via
  * \c rtnl_link_set_* functions.
  *
- * @return New netlink message
+ * @return 0 on success or a negative error code.
  * @note Not all attributes can be changed, see
  *       \ref link_changeable "Changeable Attributes" for more details.
  */
diff --git a/lib/msg.c b/lib/msg.c
index 5c852c0..62f0911 100644
--- a/lib/msg.c
+++ b/lib/msg.c
@@ -27,7 +27,7 @@
  * Netlink header type \c NLMSG_DONE.
  *
  * @par
- * The Netlink message header (\link nlmsghdr struct nlmsghdr\endlink) is shown below.
+ * The Netlink message header (struct nlmsghdr) is shown below.
  * @code   
  * 0                   1                   2                   3
  * 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
diff --git a/lib/object.c b/lib/object.c
index d881ac9..4a1b356 100644
--- a/lib/object.c
+++ b/lib/object.c
@@ -63,9 +63,11 @@ struct nl_object *nl_object_alloc(struct nl_object_ops *ops)
 }
 
 /**
- * Allocate a new object of kind specified by the name
+ * Allocate new object of kind specified by the name
  * @arg kind		name of object type
- * @return The new object or nULL
+ * @arg result		Result pointer
+ *
+ * @return 0 on success or a negative error code.
  */
 int nl_object_alloc_name(const char *kind, struct nl_object **result)
 {
diff --git a/lib/route/class.c b/lib/route/class.c
index 47356e2..a0f3758 100644
--- a/lib/route/class.c
+++ b/lib/route/class.c
@@ -309,11 +309,12 @@ void rtnl_class_foreach_cls(struct rtnl_class *class, struct nl_cache *cache,
  * @arg sk		Netlink socket.
  * @arg ifindex		interface index of the link the classes are
  *                      attached to.
+ * @arg result		Result pointer
  *
  * Allocates a new cache, initializes it properly and updates it to
  * include all classes attached to the specified interface.
  *
- * @return The cache or NULL if an error has occured.
+ * @return 0 on success or a negative error code.
  */
 int rtnl_class_alloc_cache(struct nl_sock *sk, int ifindex,
 			   struct nl_cache **result)
diff --git a/lib/route/link.c b/lib/route/link.c
index f9039a1..bfb4150 100644
--- a/lib/route/link.c
+++ b/lib/route/link.c
@@ -1036,6 +1036,7 @@ struct rtnl_link *rtnl_link_get_by_name(struct nl_cache *cache,
  * @arg old		link to be changed
  * @arg tmpl		template with requested changes
  * @arg flags		additional netlink message flags
+ * @arg result		Result pointer
  *
  * Builds a new netlink message requesting a change of link attributes.
  * The netlink message header isn't fully equipped with all relevant
@@ -1045,7 +1046,7 @@ struct rtnl_link *rtnl_link_get_by_name(struct nl_cache *cache,
  * and \a tmpl must contain the attributes to be changed set via
  * \c rtnl_link_set_* functions.
  *
- * @return New netlink message
+ * @return 0 on success or a negative error code.
  * @note Not all attributes can be changed, see
  *       \ref link_changeable "Changeable Attributes" for more details.
  */
diff --git a/lib/route/neigh.c b/lib/route/neigh.c
index aa19faa..0cd0366 100644
--- a/lib/route/neigh.c
+++ b/lib/route/neigh.c
@@ -408,7 +408,7 @@ void rtnl_neigh_put(struct rtnl_neigh *neigh)
 
 /**
  * Build a neighbour cache including all neighbours currently configured in the kernel.
- * @arg sk		Netlink socket.
+ * @arg sock		Netlink socket.
  * @arg result		Pointer to store resulting cache.
  *
  * Allocates a new neighbour cache, initializes it properly and updates it
diff --git a/lib/route/pktloc.c b/lib/route/pktloc.c
index 823a3c7..4d7d9dd 100644
--- a/lib/route/pktloc.c
+++ b/lib/route/pktloc.c
@@ -20,7 +20,7 @@
  * library and provides a well defined set of definitions for most common
  * protocol fields.
  *
- * @subsection pktloc_examples Examples
+ * @section pktloc_examples Examples
  * @par Example 1.1 Looking up a packet location
  * @code
  * struct rtnl_pktloc *loc;
@@ -151,6 +151,7 @@ errout:
 /**
  * Lookup packet location alias
  * @arg name		Name of packet location.
+ * @arg result		Result pointer
  *
  * Tries to find a matching packet location alias for the supplied
  * packet location name.
diff --git a/lib/route/route.c b/lib/route/route.c
index c85c225..f684f96 100644
--- a/lib/route/route.c
+++ b/lib/route/route.c
@@ -64,13 +64,14 @@ static int route_request_update(struct nl_cache *c, struct nl_sock *h)
  * @arg sk		Netlink socket.
  * @arg family		Address family of routes to cover or AF_UNSPEC
  * @arg flags		Flags
+ * @arg result		Result pointer
  *
  * Allocates a new cache, initializes it properly and updates it to
  * contain all routes currently configured in the kernel.
  *
  * @note The caller is responsible for destroying and freeing the
  *       cache after using it.
- * @return The cache or NULL if an error has occured.
+ * @return 0 on success or a negative error code.
  */
 int rtnl_route_alloc_cache(struct nl_sock *sk, int family, int flags,
 			   struct nl_cache **result)
diff --git a/lib/route/rule.c b/lib/route/rule.c
index 36672d3..8fa54e9 100644
--- a/lib/route/rule.c
+++ b/lib/route/rule.c
@@ -319,7 +319,7 @@ void rtnl_rule_put(struct rtnl_rule *rule)
 
 /**
  * Build a rule cache including all rules currently configured in the kernel.
- * @arg sk		Netlink socket.
+ * @arg sock		Netlink socket.
  * @arg family		Address family or AF_UNSPEC.
  * @arg result		Pointer to store resulting cache.
  *
@@ -421,6 +421,7 @@ nla_put_failure:
  * Build netlink request message to add a new rule
  * @arg tmpl		template with data of new rule
  * @arg flags		additional netlink message flags
+ * @arg result		Result pointer
  *
  * Builds a new netlink message requesting a addition of a new
  * rule. The netlink message header isn't fully equipped with
@@ -428,7 +429,7 @@ nla_put_failure:
  * or supplemented as needed. \a tmpl must contain the attributes of the new
  * address set via \c rtnl_rule_set_* functions.
  * 
- * @return The netlink message
+ * @return 0 on success or a negative error code.
  */
 int rtnl_rule_build_add_request(struct rtnl_rule *tmpl, int flags,
 				struct nl_msg **result)
@@ -476,6 +477,7 @@ int rtnl_rule_add(struct nl_sock *sk, struct rtnl_rule *tmpl, int flags)
  * Build a netlink request message to delete a rule
  * @arg rule		rule to delete
  * @arg flags		additional netlink message flags
+ * @arg result		Result pointer
  *
  * Builds a new netlink message requesting a deletion of a rule.
  * The netlink message header isn't fully equipped with all relevant
@@ -483,7 +485,7 @@ int rtnl_rule_add(struct nl_sock *sk, struct rtnl_rule *tmpl, int flags)
  * or supplemented as needed. \a rule must point to an existing
  * address.
  *
- * @return The netlink message
+ * @return 0 on success or a negative error code.
  */
 int rtnl_rule_build_delete_request(struct rtnl_rule *rule, int flags,
 				   struct nl_msg **result)