Get Doxygen working nicely

Anyone who ends up working on the code can just use doxygen to generate the documentation themselves.
We'll include the generated documentation with the final release.

Document stuff!

diff --git a/server/Doxyfile b/server/Doxyfile
index 99b48c6..dc0e696 100644 (file)
--- a/server/Doxyfile
+++ b/server/Doxyfile
@@ -26,7 +26,7 @@ DOXYFILE_ENCODING      = UTF-8
 # identify the project. Note that if you do not use Doxywizard you need
 # to put quotes around the project name if it contains spaces.
 
-PROJECT_NAME           = "My Project"
+PROJECT_NAME           = "MCTX3420 Server Software"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number.
 # This could be handy for archiving the generated documentation or
@@ -38,7 +38,7 @@ PROJECT_NUMBER         =
 # for a project that appears at the top of each page and should give viewer
 # a quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          =
+PROJECT_BRIEF          = Server side software to poll sensors, control actuators, and allow remote access
 
 # With the PROJECT_LOGO tag one can specify an logo or icon that is
 # included in the documentation. The maximum height of the logo should not
@@ -52,7 +52,7 @@ PROJECT_LOGO           =
 # If a relative path is entered, it will be relative to the location
 # where doxygen was started. If left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       =
+OUTPUT_DIRECTORY       = doc
 
 # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
 # 4096 sub-directories (in 2 levels) under the output directory of each output
@@ -184,7 +184,7 @@ SEPARATE_MEMBER_PAGES  = NO
 # The TAB_SIZE tag can be used to set the number of spaces in a tab.
 # Doxygen uses this value to replace tabs by spaces in code fragments.
 
-TAB_SIZE               = 8
+TAB_SIZE               = 4
 
 # This tag can be used to specify a number of aliases that acts
 # as commands in the documentation. An alias has the form "name=value".
@@ -207,7 +207,7 @@ TCL_SUBST              =
 # For instance, some of the names that are used will be different. The list
 # of all members will be omitted, etc.
 
-OPTIMIZE_OUTPUT_FOR_C  = NO
+OPTIMIZE_OUTPUT_FOR_C  = YES
 
 # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java
 # sources only. Doxygen will then generate output that is more tailored for

diff --git a/server/README b/server/README
index 835ef0d..7d26785 100644 (file)
--- a/server/README
+++ b/server/README
@@ -1,7 +1,9 @@
-This code will run on the Raspberry Pi server.
+This code will run on the server.
 
 The software will implement an interface between requests made by a browser using HTTP and low level sensors/control on the server.
 
-Multiple threads will be used; one running a HTTP server, and one or more for interacting with sensors/actuators.
-A watchdog program should be created to start the main server program and handle software crashes.
+Multiple threads will be used; one responding to HTTP requests, and one or more for interacting with sensors/actuators.
+A watchdog bash script can becreated to start the main server program and handle software crashes.
+
+Note: Documentation can be generated using Doxygen.
 

diff --git a/server/log.c b/server/log.c
index bd41936..62fe890 100644 (file)
--- a/server/log.c
+++ b/server/log.c
@@ -16,8 +16,7 @@ static char * unspecified_funct = (char*)"???";
 // --- Function implementations --- //
 
 /**
- * @funct Log
- * @purpose Print a message to stderr
+ * Print a message to stderr
  * @param level - Specify how severe the message is.
        If level is higher (less urgent) than the program's verbosity (see options.h) no message will be printed
  * @param funct - String indicating the function name from which this function was called.
@@ -72,8 +71,7 @@ void Log(int level, char * funct, char * fmt, ...)
 }
 
 /**
- * @funct Fatal
- * @purpose Handle a Fatal error in the program by printing a message and exiting the program
+ * Handle a Fatal error in the program by printing a message and exiting the program
        CALLING THIS FUNCTION WILL CAUSE THE PROGAM TO EXIT
  * @param funct - Name of the calling function
  * @param fmt - A format string

diff --git a/server/main.c b/server/main.c
index 71f2aba..56794f2 100644 (file)
--- a/server/main.c
+++ b/server/main.c
@@ -1,6 +1,6 @@
 /**
  * @file main.c
- * @purpose Entry point to the program, starts threads, handles cleanup on program exit
+ * @purpose main and its helper functions, signal handling and cleanup functions
  */
 
 #define _POSIX_C_SOURCE 200809L // For strsignal to work
@@ -22,35 +22,31 @@ Options g_options; // options passed to program through command line arguments
 // --- Function definitions --- //
 
 /**
- * @funct ParseArguments
- * @purpose Parse command line arguments, set up an options variable
- * @param argc - Num args
- * @param argv - Array of args
- * @param opts - Pointer to options.  &g_options
+ * Parse command line arguments, initialise g_options
+ * @param argc - Number of arguments
+ * @param argv - Array of argument strings
  */
-void ParseArguments(int argc, char ** argv, Options * opts)
+void ParseArguments(int argc, char ** argv)
 {
-       opts->program = argv[0]; // program name
-       opts->verbosity = LOGDEBUG; // default log level
-       Log(LOGDEBUG, "ParseArguments", "Called as %s with %d arguments.", opts->program, argc);
+       g_options.program = argv[0]; // program name
+       g_options.verbosity = LOGDEBUG; // default log level
+       Log(LOGDEBUG, "ParseArguments", "Called as %s with %d arguments.", g_options.program, argc);
 }
 
 /**
- * @funct SignalHandler
- * @purpose Handle signals
- * @param sig - The signal
+ * Handle a signal
+ * @param signal - The signal number
  */
-void SignalHandler(int sig)
+void SignalHandler(int signal)
 {
        // At the moment just always exit.
        // Call `exit` so that Cleanup will be called to... clean up.
-       Log(LOGWARN, "SignalHandler", "Got signal %d (%s). Exiting.", sig, strsignal(sig));
+       Log(LOGWARN, "SignalHandler", "Got signal %d (%s). Exiting.", signal, strsignal(signal));
        exit(sig);
 }
 
 /**
- * @funct Cleanup
- * @purpose Called when program exits
+ * Cleanup before the program exits
  */
 void Cleanup()
 {
@@ -60,8 +56,7 @@ void Cleanup()
 }
 
 /**
- * @funct main
- * @purpose Main entry point; start worker threads, setup signal handling, wait for threads to exit, exit
+ * Main entry point; start worker threads, setup signal handling, wait for threads to exit, exit
  * @param argc - Num args
  * @param argv - Args
  * @returns 0 on success, error code on failure

diff --git a/server/options.h b/server/options.h
index 66cad6c..297acf4 100644 (file)
--- a/server/options.h
+++ b/server/options.h
@@ -1,18 +1,23 @@
 /**
  * @file options.h
- * @purpose Declaration of structure to handle options passed to program
+ * @purpose Define the Options structure and the g_options variable
  */
 
 #ifndef _OPTIONS_H
 #define _OPTIONS_H
 
+
+/** Store options passed or calculated from arguments to the program **/
 typedef struct
 {
-       const char * program; //name of program
-       int verbosity; // verbosity level
+       /** Name of program **/
+       const char * program;
+       /** Determines at what level log messages are shown **/
+       int verbosity;
 
 } Options;
 
-extern Options g_options; // global options structure
+/** The only instance of the Options struct **/
+extern Options g_options;
 
 #endif //_OPTIONS_H

diff --git a/server/sensor.c b/server/sensor.c
index e69de29..d1d8b9f 100644 (file)
--- a/server/sensor.c
+++ b/server/sensor.c
@@ -0,0 +1,17 @@
+/**
+ * @file sensor.c
+ * @purpose Implementation of sensor thread
+ * TODO: Finalise implementation
+ */
+
+#include "sensor.h"
+
+/**
+ * Run the main sensor polling loop
+ * @param args - IGNORED (void* required to use the function with pthreads)
+ * @returns NULL (void* required to use the function with pthreads)
+ */
+void * Sensor_Main(void * args)
+{
+       
+}

diff --git a/server/sensor.h b/server/sensor.h
index d0ab7d5..b9a5aad 100644 (file)
--- a/server/sensor.h
+++ b/server/sensor.h
@@ -1,9 +1,10 @@
+
 /**
  * @file sensor.h
- * @purpose Declarations for sensor thread stuff
+ * @purpose Declarations for sensor thread related stuff
  */
 
-///TODO: Add more; this is currently just for testing
+
 
 #ifndef _SENSOR_H
 #define _SENSOR_H