added more inline documentation

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

include/cfg.h

@@ -1,8 +1,8 @@
-/**
+/** Configuration file parser.
- * Configuration parser
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
+ * @file cfg.h
  */
 
 #ifndef _CFG_H_
@@ -13,6 +13,7 @@
 struct node;
 struct path;
 
+/// Global configuration
 struct config {
 	/// Name of this node
 	const char *name;
@@ -27,7 +28,9 @@ struct config {
 	/// Protocol version of UDP packages
 	int protocol;
 	/// Number of parsed paths
-	int path_count, node_count;
+	int path_count;
+	/// Number of parsed nodes
+	int node_count;
 
 	/// libconfig object
 	config_t obj;
@@ -38,18 +41,41 @@ struct config {
 	struct path *paths;
 };
 
-/**
+/** Parse configuration file and store settings in supplied struct config.
- * @brief Parse configuration file and store settings in suplied struct
  *
  * @param c A libconfig object
  * @param g The global configuration structure (also contains the config filename)
  */
 int config_parse(config_t *c, struct config *g);
 
+/** Parse the global section of a configuration file.
+ *
+ * @param c A libconfig object pointing to the root of the file
+ * @param g The global configuration file
+ * @return
+ *  - 0 on success
+ *  - otherwise an error occured
+ */
 int config_parse_global(config_setting_t *c, struct config *g);
 
+/** Parse a single path and add it to the global configuration.
+  *
+ * @param c A libconfig object pointing to the path
+ * @param g The global configuration file
+ * @return
+ *  - 0 on success
+ *  - otherwise an error occured
+ */
 int config_parse_path(config_setting_t *c, struct config *g);
 
+/** Parse a single node and add it to the global configuration.
+  *
+ * @param c A libconfig object pointing to the node
+ * @param g The global configuration file
+ * @return
+ *  - 0 on success
+ *  - otherwise an error occured
+ */
 int config_parse_node(config_setting_t *c, struct config *g);
 
 #endif /* _CFG_H_ */

include/config.h

@@ -1,8 +1,10 @@
-/**
+/** Static server configuration
- * Configuration
+ * 
+ * This file contains some defines which 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
+ * @file config.h
  */
 
 #ifndef _CONFIG_H_

include/msg.h

@@ -1,8 +1,8 @@
-/**
+/** Message format and message related functions
- * Message format
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
+ * @file msg.h
  */
 
 #ifndef _MSG_H_
@@ -15,10 +15,9 @@
 #include "node.h"
 
 #if PROTOCOL == 0
-/**
+/** The format of a message (OPAL-RT example format).
- * The format of a message (OPAL-RT example format)
  *
- * This struct defines the format of a message (protocol version 0)
+ * This struct defines the format of a message (protocol version 0).
  * Its declared as "packed" because it represents the "on wire" data.
  */
 struct msg
@@ -33,10 +32,9 @@ struct msg
 	double data[MAX_VALUES];
 } __attribute__((packed));
 #elif PROTOCOL == 1
-/**
+/** Next generation message format for RTDS integration.
- * Next generation message format for RTDS integration
  *
- * This struct defines the format of a message (protocol version 1)
+ * This struct defines the format of a message (protocol version 1).
  * Its declared as "packed" because it represents the "on wire" data.
  */
 struct msg
@@ -72,8 +70,7 @@ struct msg
   #error "Unknown protocol version!"
 #endif
 
-/**
+/** Print a raw UDP message in human readable form.
- * @brief Print a raw UDP packge in human readable form
  *
  * @param f The file stream
  * @param msg A pointer to the message
@@ -83,8 +80,7 @@ struct msg
  */
 int msg_fprint(FILE *f, struct msg *m);
 
-/**
+/** Read a message from a file stream.
- * @brief Read a message from a file stream
  *
  * @param f The file stream
  * @param m A pointer to the message
@@ -94,15 +90,13 @@ int msg_fprint(FILE *f, struct msg *m);
  */
 int msg_fscan(FILE *f, struct msg *m);
 
-/**
+/** Change the values of an existing message in a random fashion.
- * @brief Change the values of an existing message in a random fashion
  *
- * @param msg A pointer to the message whose values will be updated
+ * @param m A pointer to the message whose values will be updated
  */
 void msg_random(struct msg *m);
 
-/**
+/** Send a message to a node.
- * @brief Send a message to a node
  *
  * @param m A pointer to the message
  * @param n A pointer to the node
@@ -112,8 +106,7 @@ void msg_random(struct msg *m);
  */
 int msg_send(struct msg *m, struct node *n);
 
-/**
+/** Receive a message from a node.
- * @brief Receive a message from a node
  *
  * @param m A pointer to the message
  * @param n A pointer to the node

include/node.h

@@ -1,5 +1,4 @@
-/**
+/** Nodes
- * Nodes
  *
  * The S2SS server connects multiple nodes.
  * There are multiple types of nodes:
@@ -9,6 +8,7 @@
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
+ * @file node.h
  */
 
 #ifndef _NODE_H_
@@ -17,6 +17,10 @@
 #include <sys/socket.h>
 #include <netinet/in.h>
 
+/** The type of a node.
+ *
+ * This type is used to determine the message format of the remote node
+ */
 enum node_type
 {
 	NODE_INVALID,
@@ -27,32 +31,39 @@ enum node_type
 	NODE_SIM_DSP
 };
 
+/** The datastructure for a node.
+ *
+ * Every entity which exchanges messages is represented by a node.
+ */
 struct node
 {
 	/// The socket descriptor
 	int sd;
 
-	// Local address of the socket
-	struct sockaddr_in local;
-
-	// Remote address of the socket
-	struct sockaddr_in remote;
-
 	/// The type of this node
 	enum node_type type;
 
+	/// Local address of the socket
+	struct sockaddr_in local;
+	/// Remote address of the socket
+	struct sockaddr_in remote;
+
+
 	/// A short identifier of the node
 	const char *name;
 };
 
-/**
+/** Create a new node.
- * @brief Create a new node
  *
  * Memory is allocated dynamically and has to be freed by node_destroy()
  *
- * @param n A pointer to the node structure
+ * @param n A pointer to the node structure.
- * @param name An acroynm, describing the node
+ * @param name An acroynm which describes the node.
- * @param type The type of a node (server, simulator, workstation)
+ * @param type The type of a node (server, simulator, workstation).
+ * @param local The local address of this node.
+ *	This is where to server is listening for the arrival of new messages.
+ * @param remote The local address of this node.
+ * 	This is where messages are sent to.
  * @return
  *  - 0 on success
  *  - otherwise on error occured
@@ -60,8 +71,7 @@ struct node
 int node_create(struct node *n, const char *name, enum node_type type,
 	struct sockaddr_in local, struct sockaddr_in remote);
 
-/**
+/** Connect and bind the UDP socket of this node
- * @brief Connect and bind the UDP socket of this node
  *
  * @param n A pointer to the node structure
  * @return
@@ -70,8 +80,7 @@ int node_create(struct node *n, const char *name, enum node_type type,
  */
 int node_connect(struct node *n);
 
-/**
+/** Disconnect the UDP socket of this node.
- * @brief Disconnect the UDP socket of this node
  *
  * @param n A pointer to the node structure
  * @return
@@ -80,16 +89,14 @@ int node_connect(struct node *n);
  */
 int node_disconnect(struct node *n);
 
-/**
+/** Lookup node type from string.
- * @brief Lookup node type from string
  *
  * @param str The string containing the node type
  * @return The node type enumeration value
  */
 enum node_type node_lookup_type(const char *str);
 
-/**
+/** Search list of nodes for a name.
- * @brief Search list of nodes for a name
  *
  * @param str The name of the wanted node
  * @param nodes A pointer to the first list element

include/path.h

@@ -1,8 +1,8 @@
-/**
+/** Message paths
- * Message paths
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
+ * @file path.h
  */
 
 #ifndef _PATH_H_
@@ -14,15 +14,22 @@
 #include "node.h"
 #include "msg.h"
 
-/**
+/** The datastructure for a path
- * @brief The datastructure for a path
+ *
+ * @todo Add support for multiple outgoing nodes
  */
 struct path
 {
-	/// Pointers to the incoming and outgoing node
+	/// Pointer to the incoming node
-	struct node *in, *out;
+	struct node *in;
+	/// Pointer to the outgoing node
+	struct node *out;
 
-	/// If non NULL this function is called for every received message
+	/** If non NULL this function is called for every received message.
+	 *
+	 * This hook can be used to filter messages on a user-defined criteria.
+	 * If the function has a non-zero return value the message will be dropped.
+	 */
 	int (*hook)(struct msg *m);
 
 	/// Counter for received messages
@@ -37,25 +44,24 @@ struct path
 	/// Last known message number
 	unsigned int sequence;
 
-	/// The path thread
+	/// The thread for this path
 	pthread_t tid;
 };
 
-/**
+/** Setup a new path.
- * @brief Setup a new path
  *
  * @param p A pointer to the path structure
  * @param in The node we are receiving messages from
- * @param out The nodes we are sending to
+ * @param out The destination node
- * @param len count of outgoing nodes
  * @return
  *  - 0 on success
  *  - otherwise an error occured
  */
 int path_create(struct path *p, struct node *in, struct node *out);
 
-/**
+/** Start a path.
- * @brief Start a path
+ *
+ * Start a new pthread for receiving/sending messages over this path.
  *
  * @param p A pointer to the path struct
  * @return
@@ -64,8 +70,7 @@ int path_create(struct path *p, struct node *in, struct node *out);
  */
 int path_start(struct path *p);
 
-/**
+/** Stop a path.
- * @brief Stop a path
  *
  * @param p A pointer to the path struct
  * @return

include/utils.h

@@ -1,8 +1,8 @@
-/**
+/** Various helper functions
- * Some helper functions
  *
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
  * @copyright 2014, Institute for Automation of Complex Power Systems, EONERC
+ * @file utils.h
  */
 
 #ifndef _UTILS_H_
@@ -16,6 +16,7 @@
 struct config;
 struct sockaddr_in;
 
+/// The log level which is passed as first argument to print()
 enum log_level
 {
 	DEBUG,
@@ -24,27 +25,27 @@ enum log_level
 	ERROR
 };
 
-/**
+/** Logs variadic messages to stdout.
- * @brief Logs variadic messages to stdout
+ *
  * @param lvl The log level
  * @param fmt The format string (printf alike)
  */
 void print(enum log_level lvl, const char *fmt, ...);
 
-/**
+/** Resolve host/service name by local databases and/or nameservers.
- * @brief Resolve host/service name by local databases and/or nameservers
  *
  * @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
  */
 int resolve(const char *addr, struct sockaddr_in *sa, int flags);
 
-/**
+/** Setup various realtime related things.
- * @brief Setup various realtime realated things
  *
+ * We use the following techniques for performance tuning
  *  - Prefault the stack
  *  - Lock memory
  *  - Use FIFO scheduler with realtime priority
@@ -54,7 +55,7 @@ int resolve(const char *addr, struct sockaddr_in *sa, int flags);
  */
 void realtime_init(struct config *g);
 
-/// Check assertion and exit if failed
+/// Check assertion and exit if failed.
 #define assert(exp) do { \
 	if (!(exp)) { \
 		print(ERROR, "Assertion failed: '%s' in %s, %s:%d", \
@@ -62,36 +63,36 @@ void realtime_init(struct config *g);
 		exit(EXIT_FAILURE); \
 	} } while (0)
 
-/// Printf alike debug message with level
+/// Printf alike debug message with level.
 #define debug(lvl, msg, ...) do { \
 	if (lvl <= V) \
 		print(DEBUG, msg, ##__VA_ARGS__); \
 	} while (0)
 
-/// Printf alike info message
+/// Printf alike info message.
 #define info(msg, ...) do { \
 		print(INFO, msg, ##__VA_ARGS__); \
 	} while (0)
 
-/// Printf alike warning message
+/// Printf alike warning message.
 #define warn(msg, ...) do { \
 		print(WARN, msg, ##__VA_ARGS__); \
 	} while (0)
 
-/// Print error and exit
+/// Print error and exit.
 #define error(msg, ...) do { \
 		print(ERROR, msg, ##__VA_ARGS__); \
 		exit(EXIT_FAILURE); \
 	} while (0)
 
-/// Print error and strerror(errno)
+/// Print error and strerror(errno).
 #define perror(msg, ...) do { \
 		print(ERROR, msg ": %s", ##__VA_ARGS__, \
 			strerror(errno)); \
 		exit(EXIT_FAILURE); \
 	} while (0)
 
-/// Print configuration error and exit
+/// Print configuration error and exit.
 #define cerror(c, msg, ...) do { \
 		print(ERROR, msg " in %s:%u", ##__VA_ARGS__, \
 			config_setting_source_file(c), \
@@ -100,4 +101,3 @@ void realtime_init(struct config *g);
 	} while (0)
 
 #endif /* _UTILS_H_ */
-

src/cfg.c

@@ -15,7 +15,7 @@
 #include "path.h"
 #include "utils.h"
 
-int config_parse(config_t *cfg, struct config *g)
+int config_parse(config_t *c, struct config *g)
 {
 	config_setting_t *cfg_nodes, *cfg_paths, *cfg_root;
 
@@ -27,7 +27,7 @@ int config_parse(config_t *cfg, struct config *g)
 		);
 	}
 
-	cfg_root = config_root_setting(cfg);
+	cfg_root = config_root_setting(c);
 
 	/* Read global settings */
 	config_parse_global(cfg_root, g);