unified comment style

git-svn-id: https://zerberus.eonerc.rwth-aachen.de:8443/svn/s2ss/trunk@155 8ec27952-4edc-4aab-86aa-e87bb2611832

server/include/cfg.h

@@ -1,4 +1,8 @@
 /** Configuration file parser.
+ *
+ * The server program is configured by a single file.
+ * This config file is parsed with a third-party library:
+ *  libconfig http://www.hyperrealm.com/libconfig/
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
@@ -18,25 +22,24 @@ struct netem;
 
 /** Global configuration */
 struct settings {
-	/** Task priority (lower is better) */
+	/** Process priority (lower is better) */
 	int priority;
-	/** Core affinity of this task */
+	/** Process affinity of the server and all created threads */
 	int affinity;
 
 	/** A libconfig object pointing to the root of the config file */
 	config_setting_t *cfg;
 };
 
-/** Parse configuration file and store settings in supplied struct settings.
+/** Parse config file and store settings in supplied struct settings.
  *
  * @param filename The path to the configration file (relative or absolute)
  * @param cfg A initialized libconfig object
  * @param set The global configuration structure
  * @param nodes A linked list of nodes which should be parsed
  * @param paths A linked list of paths which should be parsed
- * @return
- *  - 0 on success
- *  - otherwise an error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int config_parse(const char *filename, config_t *cfg, struct settings *set,
 	struct node **nodes, struct path **paths);
@@ -45,9 +48,8 @@ int config_parse(const char *filename, config_t *cfg, struct settings *set,
  *
  * @param cfg A libconfig object pointing to the root of the file
  * @param set The global configuration file
- * @return
- *  - 0 on success
- *  - otherwise an error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int config_parse_global(config_setting_t *cfg, struct settings *set);
 
@@ -56,9 +58,8 @@ int config_parse_global(config_setting_t *cfg, struct settings *set);
  * @param cfg A libconfig object pointing to the path
  * @param paths Add new paths to this linked list
  * @param nodes A linked list of all existing nodes
- * @return
- *  - 0 on success
- *  - otherwise an error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int config_parse_path(config_setting_t *cfg,
 	struct path **paths, struct node **nodes);
@@ -74,7 +75,7 @@ int config_parse_path(config_setting_t *cfg,
 int config_parse_node(config_setting_t *cfg,
 	struct node **nodes);
 
-/** Parse network emulator (netem) settings
+/** Parse network emulator (netem) settings.
  *
  * @param cfg A libconfig object containing the settings
  * @param em A pointer to the settings

server/include/config.h

@@ -1,6 +1,7 @@
 /** Static server configuration
  *
- * This file contains some defines which are not part of the configuration file.
+ * This file contains some compiled-in settings.
+ * This settings are not part of the configuration file.
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

server/include/if.h

@@ -1,4 +1,7 @@
 /** Interface related functions
+ *
+ * These functions are used to manage a network interface.
+ * Most of them make use of Linux-specific APIs.
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
@@ -29,7 +32,7 @@ struct interface {
 	struct interface *next;
 };
 
-/** Get outgoing interface
+/** Get outgoing interface.
  *
  * Does a lookup in the kernel routing table to determine
  * the interface which sends the data to a certain socket
@@ -40,7 +43,7 @@ struct interface {
  */
 int if_getegress(struct sockaddr_in *sa);
 
-/** Get all IRQs for this interface
+/** Get all IRQs for this interface.
  *
  * Only MSI IRQs are determined by looking at:
  *  /sys/class/net/{ifname}/device/msi_irqs/
@@ -62,7 +65,7 @@ int if_getirqs(struct interface *i);
  */
 int if_setaffinity(struct interface *i, int affinity);
 
-/** Search list of interface for a index
+/** Search list of interface for a index.
  *
  * @param index The interface index to search for
  * @param interfaces A linked list of all interfaces

server/include/msg_format.h

@@ -20,7 +20,7 @@
 #define MSG_TYPE_START	1
 #define MSG_TYPE_STOP	2
 
-/** This message format is used by all clients
+/** This message format is used by all clients.
  *
  * @diafile msg_format.dia
  **/

server/include/path.h

@@ -15,7 +15,7 @@
 #include "node.h"
 #include "msg.h"
 
-/** The datastructure for a path
+/** The datastructure for a path.
  *
  * @todo Add support for multiple outgoing nodes
  */
@@ -86,7 +86,7 @@ int path_start(struct path *p);
  */
 int path_stop(struct path *p);
 
-/** Show some basic statistics for a path
+/** Show some basic statistics for a path.
  *
  * @param p A pointer to the path struct
  */

server/include/tc.h

@@ -41,7 +41,7 @@ typedef uint32_t tc_hdl_t;
 
 struct interface;
 
-/** Netem configuration settings
+/** Netem configuration settings.
  *
  * This struct is used to pass the netem configuration
  * from config_parse_netem() to tc_netem()
@@ -64,7 +64,7 @@ struct netem {
 	int duplicate;
 };
 
-/** Remove all queuing disciplines and filters 
+/** Remove all queuing disciplines and filters.
  *
  * @param i The interface
  * @return
@@ -73,7 +73,7 @@ struct netem {
  */
 int tc_reset(struct interface *i);
 
-/** Create a prio queueing discipline
+/** Create a priority (prio) queueing discipline.
  *
  * @param i The interface
  * @param handle The handle for the new qdisc
@@ -84,7 +84,7 @@ int tc_reset(struct interface *i);
  */
 int tc_prio(struct interface *i, tc_hdl_t handle, int bands);
 
-/** Add a new network emulator discipline
+/** Add a new network emulator (netem) discipline.
  *
  * @param i The interface
  * @param parent Make this qdisc a child of
@@ -95,7 +95,7 @@ int tc_prio(struct interface *i, tc_hdl_t handle, int bands);
  */
 int tc_netem(struct interface *i, tc_hdl_t parent, struct netem *em);
 
-/** Add a new filter based on the netfilter mark
+/** Add a new filter based on the netfilter mark.
  *
  * @param i The interface
  * @param flowid The destination class for matched traffic

server/include/utils.h

@@ -1,4 +1,4 @@
-/** Various helper functions
+/** Various helper functions.
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
@@ -44,13 +44,12 @@ void print(enum log_level lvl, const char *fmt, ...);
  * @param addr A string containing the hostname/ip and port seperated by a colon
  * @param sa A pointer to the resolved address
  * @param flags Flags for gai
- * @return
- * - 0 on success
- * - otherwise an error occured
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int resolve_addr(const char *addr, struct sockaddr_in *sa, int flags);
 
-/** Convert integer to cpu_set_t
+/** Convert integer to cpu_set_t.
  *
  * @param set A cpu bitmask
  * @return The opaque cpu_set_t datatype

server/src/cfg.c

@@ -1,4 +1,4 @@
-/** Configuration parser
+/** Configuration parser.
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

server/src/if.c

@@ -1,4 +1,4 @@
-/** Interface related functions
+/** Interface related functions.
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

server/src/msg.c

@@ -1,4 +1,4 @@
-/** Message related functions
+/** Message related functions.
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

server/src/node.c

@@ -1,4 +1,4 @@
-/** Nodes
+/** Nodes.
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

server/src/path.c

@@ -1,4 +1,4 @@
-/** Message paths
+/** Message paths.
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

server/src/random.c

@@ -1,4 +1,4 @@
-/** Generate random packages on stdout
+/** Generate random packages on stdout.
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

server/src/receive.c

@@ -1,4 +1,4 @@
-/** Receive messages from server snd print them on stdout
+/** Receive messages from server snd print them on stdout.
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

server/src/send.c

@@ -1,4 +1,4 @@
-/** Send messages from stdin to server
+/** Send messages from stdin to server.
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

server/src/server.c

@@ -1,4 +1,4 @@
-/** Main routine
+/** Main routine.
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

server/src/tc.c

@@ -1,4 +1,4 @@
-/** Traffic control: setup interface queuing desciplines
+/** Traffic control (tc): setup interface queuing desciplines.
  *
  * S2SS uses these functions to setup the network emulation feature.
  *

server/src/test.c

@@ -1,4 +1,4 @@
-/** Some basic tests
+/** Some basic tests.
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC

server/src/utils.c

@@ -1,4 +1,4 @@
-/** Some helper functions
+/** Some helper functions.
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC