improved documentation

server/include/cfg.h

@@ -72,9 +72,8 @@ int config_parse_path(config_setting_t *cfg,
  *
  * @param cfg A libconfig object pointing to the node
  * @param nodes Add new nodes to this linked list
- * @return
- *  - 0 on success
- *  - otherwise an error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int config_parse_node(config_setting_t *cfg,
 	struct node **nodes);
@@ -83,9 +82,8 @@ int config_parse_node(config_setting_t *cfg,
  *
  * @param cfg A libconfig object containing the settings
  * @param em A pointer to the settings
- * @return
- *  - 0 on success
- *  - otherwise an error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int config_parse_netem(config_setting_t *cfg, struct netem *em);
 

server/include/if.h

@@ -38,8 +38,8 @@ struct interface {
  * the interface which sends the data to a certain socket
  * address.
  *
- * @param sa A destination address for outgoing packets
- * @return The interface index
+ * @param sa A destination address for outgoing packets.
+ * @return The interface index.
  */
 int if_getegress(struct sockaddr_in *sa);
 
@@ -49,9 +49,8 @@ int if_getegress(struct sockaddr_in *sa);
  *  /sys/class/net/{ifname}/device/msi_irqs/
  *
  * @param i A pointer to the interface structure
- * @return
- *  - 0 on success
- *  - otherwise an error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int if_getirqs(struct interface *i);
 
@@ -59,17 +58,17 @@ int if_getirqs(struct interface *i);
  *
  * @param i A pointer to the interface structure
  * @param affinity A mask specifying which cores should handle this interrupt.
- * @return
- *  - 0 on success
- *  - otherwise an error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int if_setaffinity(struct interface *i, int affinity);
 
-/** Search list of interface for a index.
+/** Search the list of interfaces for a given index.
  *
  * @param index The interface index to search for
  * @param interfaces A linked list of all interfaces
- * @return A pointer to the node or NULL if not found
+ * @retval NULL if no interface with index was found.
+ * @retval >0 Success. A pointer to the interface.
  */
 struct interface* if_lookup_index(int index, struct interface *interfaces);
 

server/include/msg.h

@@ -31,9 +31,8 @@ void msg_swap(struct msg *m);
  *
  * @param f The file stream
  * @param m A pointer to the message
- * @return
- *  - 0 on success
- *  - otherwise an error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int msg_fprint(FILE *f, struct msg *m);
 
@@ -41,9 +40,8 @@ int msg_fprint(FILE *f, struct msg *m);
  *
  * @param f The file stream
  * @param m A pointer to the message
- * @return
- *  - 0 on success
- *  - otherwise an error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int msg_fscan(FILE *f, struct msg *m);
 

server/include/node.h

@@ -63,18 +63,16 @@ struct node
 /** Connect and bind the UDP socket of this node.
  *
  * @param n A pointer to the node structure
- * @return
- *  - 0 on success
- *  - otherwise on error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int node_connect(struct node *n);
 
 /** Disconnect the UDP socket of this node.
  *
  * @param n A pointer to the node structure
- * @return
- *  - 0 on success
- *  - otherwise on error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int node_disconnect(struct node *n);
 

server/include/path.h

@@ -68,18 +68,16 @@ struct path
  * Start a new pthread for receiving/sending messages over this path.
  *
  * @param p A pointer to the path struct
- * @return
- *  - 0 on success
- *  - otherwise an error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int path_start(struct path *p);
 
 /** Stop a path.
  *
  * @param p A pointer to the path struct
- * @return
- *  - 0 on success
- *  - otherwise an error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int path_stop(struct path *p);
 

server/include/tc.h

@@ -67,9 +67,8 @@ struct netem {
 /** Remove all queuing disciplines and filters.
  *
  * @param i The interface
- * @return
- *  - 0 on success
- *  - otherwise an error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int tc_reset(struct interface *i);
 
@@ -78,9 +77,8 @@ int tc_reset(struct interface *i);
  * @param i The interface
  * @param handle The handle for the new qdisc
  * @param bands The number of classes for this new qdisc
- * @return
- *  - 0 on success
- *  - otherwise an error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int tc_prio(struct interface *i, tc_hdl_t handle, int bands);
 
@@ -89,9 +87,8 @@ int tc_prio(struct interface *i, tc_hdl_t handle, int bands);
  * @param i The interface
  * @param parent Make this qdisc a child of
  * @param em The netem settings
- * @return
- *  - 0 on success
- *  - otherwise an error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int tc_netem(struct interface *i, tc_hdl_t parent, struct netem *em);
 
@@ -100,9 +97,8 @@ int tc_netem(struct interface *i, tc_hdl_t parent, struct netem *em);
  * @param i The interface
  * @param flowid The destination class for matched traffic
  * @param mark The netfilter firewall mark (sometime called 'fwmark')
- * @return
- *  - 0 on success
- *  - otherwise an error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
 */
 int tc_mark(struct interface *i, tc_hdl_t flowid, int mark);