some doxygen improvements

10 files changed, 63 insertions, 34 deletions

diff --git a/include/sitecing/cgi_component.h b/include/sitecing/cgi_component.h
index 91df689..0cad438 100644
--- a/include/sitecing/cgi_component.h
+++ b/include/sitecing/cgi_component.h
@@ -22,33 +22,24 @@ namespace sitecing {
 	    /**
 	     * The interface to site-C-ing core.
 	     */
 	    sitecing_interface_cgi* __SCIF;
 	    /**
 	     * The interface to the CGI gateway.
 	     */
 	    kingate::cgi_gateway* __CGI;
 
 	    cgi_component();
 	    virtual ~cgi_component();
 
-	    /**
-	     * @overload acomponent::__set_interface()
-	     */
 	    void __set_interface(sitecing_interface* scif);
-	    /**
-	     * @overload acomponent::__on_change_interface()
-	     */
-	    void __on_change_interface(sitecing_interface *o);
+	    void __on_change_interface(sitecing_interface *oscif);
 	    /**
 	     * Invoked on the change of the interface to the CGI.
 	     */
 	    virtual void __on_change_CGI(kingate::cgi_gateway *o);
-	    /**
-	     * @overload acomponent::__on_imports()
-	     */
 	    virtual void __on_imports();
     };
 
 }
 
 #endif /* __SITECING_CGI_COMPONENT_H */
diff --git a/include/sitecing/component_factory.h b/include/sitecing/component_factory.h
index 9ddf70d..8f103e0 100644
--- a/include/sitecing/component_factory.h
+++ b/include/sitecing/component_factory.h
@@ -33,39 +33,27 @@ namespace sitecing {
 	     */
 	    string root_so;
 	    /**
 	     * Reference to the configuration container.
 	     */
 	    configuration& config;
 
 	    /**
 	     * @param c reference to the configuration container.
 	     */
 	    component_factory(configuration& c);
 
-	    /**
-	     * @overload file_factory::get_dependencies()
-	     */
 	    virtual void get_dependencies(const string& dst,file_list_t& deps);
-	    /**
-	     * @overload file_factory::is_uptodate()
-	     */
-	    virtual bool is_uptodate(const string& dst,file_list_t *deps=NULL);
-	    /**
-	     * @overload file_factory::build()
-	     */
+	    virtual bool is_uptodate(const string& dst,file_list_t *deps=0);
 	    virtual void build(const string& dst);
-	    /**
-	     * @overload file_factory::make()
-	     */
 	    virtual void make(const string& dst);
 
 	    /**
 	     * Helper function for executing external command.
 	     * @param cmd the command to execute.
 	     * @param args the command line arguments.
 	     * @param stdo stdout for the child process.
 	     * @param stde stderr for the child process.
 	     * @return exit code.
 	     */
 	    int execute(const string& cmd,const list<string>& args,int stdo,int stde);
 	    /**
diff --git a/include/sitecing/component_so.h b/include/sitecing/component_so.h
index 3239d4a..3daceef 100644
--- a/include/sitecing/component_so.h
+++ b/include/sitecing/component_so.h
@@ -140,20 +140,26 @@ namespace sitecing {
     /**
      * The typed component instance container template.
      * @param CT the component class.
      */
     template<typename CT>
 	class so_component_t : public sitecing::so_component {
 	    public:
 		/**
 		 * @param s The untyped instance container.
 		 */
 		so_component_t(const so_component& s)
 		    : so_component(s) { }
+
+		/**
+		 * typed dereference operator
+		 * @return the pointer to the most derived component instance
+		 * @see acomponent::__the_most_derived_this()
+		 */
 		CT* operator->() {
 		    return static_cast<CT*>(ac->__the_most_derived_this());
 		}
 	};
     
 }
 
 #endif /* __SITECING_COMPONENT_SO_H */
diff --git a/include/sitecing/configuration.h b/include/sitecing/configuration.h
index 330a5a6..a2bf612 100644
--- a/include/sitecing/configuration.h
+++ b/include/sitecing/configuration.h
@@ -135,26 +135,35 @@ namespace sitecing {
 		 * Precompiled regex.
 		 */
 		pcrepp::Pcre regex;
 		/**
 		 * The action handler component.
 		 */
 		string action;
 		/**
 		 * Arguments for the action hander coponent.
 		 */
 		list<string> args;
 
+		/**
+		 * @param s regex pattern
+		 * @param a action handler
+		 */
 		action_handler_t(const string& s,const string& a)
 		    : s_regex(s), regex(s), action(a) { }
+		/**
+		 * Copy constructor
+		 *
+		 * @param s source object
+		 */
 		action_handler_t(const action_handler_t& s)
 		    : s_regex(s.s_regex), regex(s.regex), action (s.action), args(s.args) { }
 	    };
 	    /**
 	     * Type for the list of action handlers.
 	     */
 	    typedef list<action_handler_t> action_handlers_t;
 	    /**
 	     * The list of action handlers.
 	     */
 	    action_handlers_t action_handlers;
 	    /**
@@ -209,25 +218,25 @@ namespace sitecing {
 	     */
 	    struct stat st;
 
 	    /**
 	     * See if the data is still valid.
 	     * @return true if yes.
 	     */
 	    bool is_valid();
 
 	    /**
 	     * Load the configuration file.
 	     * @param config the main configuration container.
-	     * @param the configuration file.
+	     * @param cfile the configuration file.
 	     */
 	    void parse(configuration *config,const string& cfile);
     };
 
     /**
      * The main configuration container.
      */
     class configuration {
 	public:
 	    /**
 	     * @todo TODO:: document me.
 	     */
@@ -289,25 +298,25 @@ namespace sitecing {
 		flag_requests_per_child = 0x00000200,
 		/**
 		 * Was the multiprocess node (or it's absences) specified?
 		 * @see multi_process
 		 */
 		flag_multi_process      = 0x00000400,
 		/**
 		 * Was the user specified?
 		 * @see user
 		 */
 		flag_user               = 0x00000800,
 		/**
-		 * @Was the group specified?
+		 * Was the group specified?
 		 * @see group
 		 */
 		flag_group              = 0x00001000,
 		/**
 		 * Was the root to change to specified?
 		 * @see chroot
 		 */
 		flag_chroot             = 0x00002000,
 		/**
 		 * Was the file for storing PID specified?
 		 * @see pidfile
 		 */
@@ -381,40 +390,48 @@ namespace sitecing {
 	     * Directory to change root to.
 	     */
 	    string chroot;
 	    /**
 	     * The file to store PID into.
 	     */
 	    string pid_file;
 	    /**
 	     * Whether we should fork into background.
 	     */
 	    bool daemonize;
 
+	    /**
+	     * Type for the config options map
+	     * @see specs
+	     */
 	    typedef map<string,config_options> specs_t;
 	    /**
 	     * The local config options map.
 	     */
 	    specs_t specs;
+	    /**
+	     * Type for the loaded per-dir config map
+	     * @see loaded_specs
+	     */
 	    typedef map<string,loaded_options> loaded_specs_t;
 	    /**
 	     * The local config options as specified in per-dir config files
 	     * map.
 	     */
 	    loaded_specs_t loaded_specs;
 
 	    configuration();
 	    /**
 	     * @param cfile the configuration file.
-	     * @param ab @todo TODO:: document me
+	     * @param ab document me @todo TODO:: document me
 	     */
 	    configuration(const string& cfile,bool ab=false);
 
 	    /**
 	     * Parse the configuration file.
 	     * @param cfile the configuration file.
 	     */
 	    void parse(const string& cfile);
 
 	    /**
 	     * Fetch the reference to options for the very root.
 	     */
diff --git a/include/sitecing/file_factory.h b/include/sitecing/file_factory.h
index 7ec82da..43a27bb 100644
--- a/include/sitecing/file_factory.h
+++ b/include/sitecing/file_factory.h
@@ -23,31 +23,31 @@ namespace sitecing {
 	     */
 	    int depth;
 	    /**
 	     * The list of files type. The list of strings, in fact.
 	     */
 	    typedef list<string> file_list_t;
 
 	    file_factory()
 		: depth(0) { }
 
 	    /**
 	     * Fetch depndencies for the given file.
-	     * @param dst destination file.
+	     * @param dst the destination file.
 	     * @param deps where to put dependencies to.
 	     */
 	    virtual void get_dependencies(const string& dst,file_list_t& deps) = 0;
 	    /**
 	     * Check if the destination is up to day.
-	     * @param the destination file.
+	     * @param dst the destination file.
 	     * @param deps if the deps pointer is non there, the dependencies
 	     * retrieved will be stored there.
 	     * @return true if yes.
 	     * @see get_dependencies()
 	     */
 	    virtual bool is_uptodate(const string& dst,file_list_t* deps=0);
 	    /**
 	     * Build the file requested.
 	     * @param dst the file requested.
 	     */
 	    virtual void build(const string& dst) = 0;
 	    /**
diff --git a/include/sitecing/process_manager.h b/include/sitecing/process_manager.h
index 73415d3..921f159 100644
--- a/include/sitecing/process_manager.h
+++ b/include/sitecing/process_manager.h
@@ -45,25 +45,25 @@ namespace sitecing {
 	    bool die_humbly;
 
 	    process_manager();
 	    virtual ~process_manager();
 
 	    /**
 	     * The main loop.
 	     */
 	    void manage();
 
 	    /**
 	     * The worker function.
-	     * @param the slot allocated for the process.
+	     * @param slot the slot allocated for the process.
 	     */
 	    virtual void process(int slot) = 0;
 
 	    /**
 	     * @todo TODO: wish I could remember -- document me.
 	     */
 	    void manage_children();
 	    /**
 	     * @todo TODO: wish I could remember -- document me.
 	     */
 	    bool spawn_children();
 	    /**
diff --git a/include/sitecing/scoreboard.h b/include/sitecing/scoreboard.h
index 788f881..1371ab1 100644
--- a/include/sitecing/scoreboard.h
+++ b/include/sitecing/scoreboard.h
@@ -36,24 +36,27 @@ namespace sitecing {
 	     * The process is idle.
 	     */
 	    state_idle,
 	    /**
 	     * The process is accepting connection.
 	     */
 	    state_accept,
 	    /**
 	     * The process is processing request.
 	     */
 	    state_processing
 	}   state;
+	/**
+	 * Process ID
+	 */
 	pid_t pid;
     };
 
     /**
      * The scoreboard manager.
      */
     class scoreboard {
 	/**
 	 * shared memory id.
 	 */
 	int shmid;
 	public:
diff --git a/include/sitecing/sitecing_parser.h b/include/sitecing/sitecing_parser.h
index a8474f3..a53ef22 100644
--- a/include/sitecing/sitecing_parser.h
+++ b/include/sitecing/sitecing_parser.h
@@ -79,25 +79,26 @@ class sitecing_parser : public sitecing_parserFlexLexer {
 		 */
 		string initializer;
 		/**
 		 * @todo TODO: wish I could remember -- document me.
 		 */
 		bool bTypeOnly;
 
 		/**
 		 * @param t type.
 		 * @param n name.
 		 * @param i initializer.
 		 * @param bc whether it is a component.
-		 * @param bto @todo TODO: @see bTypeOnly.
+		 * @param bto document me @todo TODO:
+		 * @see bTypeOnly.
 		 */
 		member_variable(const string& t,const string& n,const string& i,bool bc = false,bool bto = false)
 		    : type(t), name(n), initializer(i), bComponent(bc), bTypeOnly(bto) { }
 	};
 	/**
 	 * The list of member variables.
 	 */
 	typedef list<member_variable> member_variables_t;
 	/**
 	 * Member variables.
 	 */
 	member_variables_t member_variables;
@@ -212,26 +213,25 @@ class sitecing_parser : public sitecing_parserFlexLexer {
 		 */
 		string _lastid;
 		/**
 		 * The name for compound modes.
 		 */
 		string _name;
 		/**
 		 * The argument declaration. Obviously for member functions.
 		 */
 		string _args;
 
 		/**
-		 * @param flags.
-		 * @see flags
+		 * @param f processing flags @see flags
 		 */
 		modus_operandi(int f = 0)
 		    : modus(modus_code), flags(f) { }
 
 		/**
 		 * Change the processing mode.
 		 */
 		void modify(modus_t m);
 
 		/**
 		 * See if we're eating up whitespaces.
 		 */
diff --git a/include/sitecing/sitecing_util.h b/include/sitecing/sitecing_util.h
index f642c74..233292c 100644
--- a/include/sitecing/sitecing_util.h
+++ b/include/sitecing/sitecing_util.h
@@ -10,49 +10,73 @@
  * @file
  * @brief utility classes and functions.
  */
 
 namespace sitecing {
     using namespace std;
 
     /**
      * Base class for utility exceptions.
      */
     class utility_error : public konforka::exception {
 	public:
+	    /**
+	     * @param fi file name
+	     * @param fu function name
+	     * @param l line number
+	     * @param w what
+	     */
 	    utility_error(const string& fi,const string& fu,int l,const string& w)
 		: konforka::exception(fi,fu,l,w) { }
     };
     
     /**
      * No prefix or suffix found to strip out.
      */
     class utility_no_affix : public utility_error {
 	public:
+	    /**
+	     * @param fi file name
+	     * @param fu function name
+	     * @param l line number
+	     * @param w what
+	     */
 	    utility_no_affix(const string& fi,const string& fu,int l,const string& w)
 		: utility_error(fi,fu,l,w) { }
     };
     /**
      * No prefix to strip found.
      */
     class utility_no_prefix : public utility_no_affix {
 	public:
+	    /**
+	     * @param fi file name
+	     * @param fu function name
+	     * @param l line number
+	     * @param w what
+	     */
 	    utility_no_prefix(const string& fi,const string& fu,int l,const string& w)
 		: utility_no_affix(fi,fu,l,w) { }
     };
     /**
      * No suffix to strip found.
      */
     class utility_no_suffix : public utility_no_affix {
 	public:
+	    /**
+	     * @param fi file name
+	     * @param fu function name
+	     * @param l line number
+	     * @param w what
+	     */
 	    utility_no_suffix(const string& fi,const string& fu,int l,const string& w)
 		: utility_no_affix(fi,fu,l,w) { }
     };
 
     /**
      * The file lock object. Released at the object destruction.
      */
     class file_lock {
 	public:
 	    /**
 	     * The file descriptor.
 	     */
diff --git a/include/sitecing/util.h b/include/sitecing/util.h
index 5750ab6..a38ae90 100644
--- a/include/sitecing/util.h
+++ b/include/sitecing/util.h
@@ -13,33 +13,33 @@
 namespace sitecing {
     using namespace std;
 
     /**
      * the html_escape options enumeration.
      */
     enum html_escape_options {
 	/**
 	 * Turn spaces into &nbsp;
 	 */
 	html_escape_nbsp       = 0x0001,
 	/**
-	 * Turn newlines into <br/> or <br>.
+	 * Turn newlines into br/ or br.
 	 */
 	html_escape_br         = 0x0002,
 	/**
 	 * Turn quotes to &quot;
 	 */
 	html_escape_quot       = 0x0004,
 	/**
-	 * Do not put '/' into <br/> consruct.
+	 * Do not put '/' into br consruct.
 	 */
 	html_escape_br_noslash = 0x0008
     };
     /**
      * Escape string suitable for html output.
      * @param str the string.
      * @param flags options.
      * @return the string escaped.
      * @see html_escape_options
      */
     string html_escape(const string& str,int flags=html_escape_br);