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
@@ -1,54 +1,45 @@
 #ifndef __SITECING_CGI_COMPONENT_H
 #define __SITECING_CGI_COMPONENT_H
 
 #include <map>
 #include "kingate/cgi_gateway.h"
 #include "sitecing/acomponent.h"
 #include "sitecing/sitecing_interface_cgi.h"
 
 /**
  * @file
  * @brief The cgi_component class declaration.
  */
 
 namespace sitecing {
     using namespace std;
 
     /**
      * The CGI-oriented component class.
      */
     class cgi_component : virtual public acomponent {
         public:
             /**
              * 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
@@ -1,88 +1,76 @@
 #ifndef __SITECING_COMPONENT_FACTORY_H
 #define __SITECING_COMPONENT_FACTORY_H
 
 #include <string>
 #include <list>
 #include <stdexcept>
 #include "sitecing/file_factory.h"
 #include "sitecing/configuration.h"
 
 /**
  * @file
  * @brief The component_factory class declaration.
  */
 
 namespace sitecing {
     using namespace std;
 
     /**
      * @brief The components builder.
      */
     class component_factory : public file_factory {
         public:
             /**
              * Path to the source files root.
              */
             string root_source;
             /**
              * Path to the root of the intermediate files storage.
              */
             string root_intermediate;
             /**
              * Output path for .so components.
              */
             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);
             /**
              * Fetch the class name of the component.
              * @param component the component.
              * @return the class name.
              */
             string get_classname(const string& component);
             /**
              * Get the components from which the target component has been
              * derived.
              * @param component the target component
              * @param rv where to store the list of ancestors.
              */
             void get_ancestors(const string& component,file_list_t &rv);
     };
 
 }
 
 #endif /* __SITECING_COMPONENT_FACTORY_H */
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
@@ -104,56 +104,62 @@ namespace sitecing {
              * @param scif pointer to the interface to the site-C-ing core.
              */
             so_component(component_so *h,sitecing_interface *scif);
             /**
              * Copy constructor
              * @param s source instance.
              */
             so_component(const so_component& s)
                 : hen(0), ac(0) { attach(s); }
             ~so_component() { detach(); }
 
             /**
              * Assignment operator.
              * @param s source instance.
              */
             so_component& operator=(const so_component& s) {
                 attach(s); return *this;
             }
 
             /**
              * @todo TODO: wish I could remember the details -- document me.
              * @param h the 'class' object.
              * @param a the instance to be attached.
              */
             void attach(component_so *h,acomponent *a);
             /**
              * @todo TODO: wish I could remember the details -- document me.
              * @param s the source instance.
              */
             void attach(const so_component& s) { attach(s.hen,s.ac); }
             /**
              * @todo TODO: wish I could remember the details -- document me.
              */
             void detach();
     };
 
     /**
      * 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
@@ -99,358 +99,375 @@ namespace sitecing {
              * The flags to pass to compiler.
              */
             list<string> cpp_flags;
             /**
              * The flags to pass to linker.
              */
             list<string> ld_flags;
             /**
              * Whether to build inexstent and outdated components.
              */
             bool build;
             /**
              * Whether to track cpp dependencies.
              */
             bool cpp_deps;
             /**
              * The component handling caught exceptions.
              */
             string exception_handler;
             /**
              * Enforced intermediate dependencies.
              */
             list<string> intermediate_deps;
             /**
              * Enforced depencies for .so objects.
              */
             list<string> so_deps;
             /**
              * The action handler type.
              */
             struct action_handler_t {
                 /**
                  * The regexp to check request against.
                  */
                 string s_regex;
                 /**
                  * 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;
             /**
              * Type for the map of HTTP status handler components.
              */
             typedef map<string,string> http_status_handlers_t;
             /**
              * The map of HTTP status handler components.
              */
             http_status_handlers_t http_status_handlers;
             /**
              * Files to be built automatically.
              */
             list<string> auto_build_files;
 
             config_options()
                 : flags(0) { }
 
             /**
              * Look up if there is an action handler for the target defined.
              * @param target the target component.
              * @return the pointer to handler or zero.
              */
             action_handler_t *lookup_action_handler(const string& target);
             /**
              * Look up if there is a handler defined for the HTTP status.
              * @param status HTTP status
              * @return the handler component.
              */
             string lookup_http_status_handler(const string& status);
             /**
              * Check whether the file should be build automatically.
              * @param fn file name.
              * @param rv reference to the boolean where the answer should go.
              * @return true if we know the answer.
              */
             bool match_autobuild_files(const char *fn,bool &rv);
     };
 
     /**
      * Configuration data container for the configuration loaded from disk file.
      */
     class loaded_options : public config_options {
         public:
             /**
              * The file where configuration originates from.
              */
             string source_file;
             /**
              * The stat structure for the source file as it was when we have
              * loaded it.
              */
             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.
              */
             bool autobuild;
             /**
              * The flags enumeration.
              */
             enum _flags {
                 /**
                  * Was the source root specified?
                  * @see root_source
                  */
                 flag_root_source        = 0x00000001,
                 /**
                  * Was the root for intermediate files specified?
                  * @see root_intermediate
                  */
                 flag_root_intermediate  = 0x00000002,
                 /**
                  * Was the root for the resulting .so files specified?
                  * @see root_so
                  */
                 flag_root_so            = 0x00000004,
                 /**
                  * Was the socket to listen to specified?
                  * @see listen_socket
                  */
                 flag_listen_socket      = 0x00000008,
                 /**
                  * Was the per-dir config file name specified.
                  * @see rc_file_name
                  */
                 flag_rc_file_name       = 0x00000010,
                 /**
                  * Was the minimum number of child processes specified?
                  * @see min_children
                  */
                 flag_min_children       = 0x00000020,
                 /**
                  * Was the maximum number of child processes specified?
                  * @see max_children
                  */
                 flag_max_children       = 0x00000040,
                 /**
                  * Was the minimum number of spare child processes specified?
                  * @see min_spare_children
                  */
                 flag_min_spare_children = 0x00000080,
                 /**
                  * Was he maximum number of spare child processes specified?
                  * @see max_spare_children
                  */
                 flag_max_spare_children = 0x00000100,
                 /**
                  * Was the number of requests to handle per child process
                  * specified?
                  * @see requests_per_child
                  */
                 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
                  */
                 flag_pid_file           = 0x00004000,
                 /**
                  * Was it specified wether we should daemonize the process?
                  * @see daemonize
                  */
                 flag_daemonize          = 0x00008000
             };
             /**
              * The flags specifying what parts of the configuration has been
              * loaded into the object.
              */
             long flags;
 
             /**
              * The root for the components source code.
              */
             string root_source;
             /**
              * The root for intermediate files.
              */
             string root_intermediate;
             /**
              * The root for .so files.
              */
             string root_so;
             /**
              * Socket to bind to
              */
             string listen_socket;
             /**
              * per-dir config file name.
              */
             string rc_file_name;
             /**
              * The minimum number of child processes in multiprocess mode.
              */
             int min_children;
             /**
              * The maxium number of child processes in multiprocess mode.
              */
             int max_children;
             /**
              * The minimum number of spare chidren in multiprocess mode.
              */
             int min_spare_children;
             /**
              * The maximum number of spare children in multiprocess mode.
              */
             int max_spare_children;
             /**
              * The number of requests the child process should handle before
              * exiting.
              */
             int requests_per_child;
             /**
              * Whether we should run in multiprocess mode or not.
              */
             bool multi_process;
             /**
              * User to change to.
              */
             string user;
             /**
              * Group to set to.
              */
             string group;
             /**
              * 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.
              */
             config_options& root_options() { return specs[""]; }
             /**
              * Lookup where the certain config option for the target lies in.
              * @param target the target component.
              * @param flag the flag specifying the option we're looking for.
              * @return the destination options continer or zero.
              */
             config_options* lookup_config(const string& target,int flag);
             /**
              * Lookup the action handler for the target.
              * @param target the target request.
              * @return the action handler or zero.
              */
             config_options::action_handler_t *lookup_action_handler(const string& target);
             /**
              * Lookup the HTPP status handler for the target.
              * @param target the target.
              * @param status the HTTP status.
              * @return the handler component.
              */
             string lookup_http_status_handler(const string& target,const string& status);
             /**
              * Lookup the options loaded from per-dir config for the target
              * @param target the target.
              * @return options container or zero.
              */
             loaded_options* lookup_loaded_options(const string& target);
             /**
              * Check whether the components for the target should be prebuilt.
              * @param target the target.
              * @param fn file name.
              * @return true if yes.
              */
             bool match_autobuild_files(const string& target,const char *fn);
     };
 
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
@@ -1,64 +1,64 @@
 #ifndef __SITECING_FILE_FACTORY_H
 #define __SITECING_FILE_FACTORY_H
 
 #include <string>
 #include <list>
 
 /**
  * @file
  * @brief the file_factory class declaration.
  */
 
 namespace sitecing {
     using namespace std;
 
     /**
      * The factory class. Does the job similar to that which is done by make
      * utility.
      */
     class file_factory {
         public:
             /**
              * The recursion depth.
              */
             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;
             /**
              * Make the file requested, which means: build it, unless it's
              * uptodate.
              * @see is_uptodate()
              * @see build()
              */
             virtual void make(const string& dst);
     };
 
 }
 
 #endif /* __SITECING_FILE_FACTORY_H */
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
@@ -9,81 +9,81 @@
  */
 
 namespace sitecing {
 
     /**
      * The process manager.
      */
     class process_manager {
         public:
             /**
              * Minimum number of child processes.
              */
             int min_children;
             /**
              * Maxinum number of child processes.
              */
             int max_children;
             /**
              * Minimum number of spare child processes.
              */
             int min_spare_children;
             /**
              * Maxiumum number of spare child processes.
              */
             int max_spare_children;
             /**
              * The scoreboard.
              */
             scoreboard sboard;
             /**
              * We're in the process of shutting down.
              */
             bool finishing;
             /**
              * @todo TODO: wish I could rememer -- document me.
              */
             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();
             /**
              * @todo TODO: wish I could remember -- document me.
              */
             bool kill_children();
             /**
              * @todo TODO: wish I could remember -- document me.
              */
             void spawn_child();
             /**
              * @todo TODO: wish I could remember -- document me.
              */
             void wait_for_children(bool hang=false);
             /**
              * @todo TODO: wish I could remember -- document me.
              */
             void collect_dead_souls(bool actively=false);
     };
 
 }
 
 #endif /* __SITECING_PROCESS_MANAGER_H */
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
@@ -1,95 +1,98 @@
 #ifndef __SITECING_SCOREBOARD_H
 #define __SITECING_SCOREBOARD_H
 
 #include <sys/types.h>
 
 /**
  * @file
  * @brief the scoreboard manager.
  */
 
 /**
  * @def MAX_SITECING_SCOREBOARD_SLOTS
  * The maximum number of slots scoreboard can hold.
  */
         #define         MAX_SITECING_SCOREBOARD_SLOTS512
 
 namespace sitecing {
   
     /**
      * The scoreboard slot.
      */
     struct scoreboard_slot {
         /**
          * The state enumeration.
          */
         enum _state {
             /**
              * The slot is free.
              */
             state_free = 0,
             /**
              * The slot is allocated.
              */
             state_allocated,
             /**
              * 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:
             /**
              * Pointer to the scoreboard slots.
              */
             scoreboard_slot *slots;
 
             scoreboard();
             ~scoreboard();
 
             /**
              * Allocate a scoreboard slot.
              * @return the slot number.
              */
             int allocate_slot();
             /**
              * Free the slot allocated.
              * @param slot the slot number.
              */
             void free_slot(int slot);
 
             /**
              * Get the pointer to the slot.
              * @param slot the slot number.
              * @return the pointer.
              */
             scoreboard_slot *get_slot(int slot);
             /**
              * Find the slot corresponding to the process ID.
              * @param pid the process id.
              * @return the slot number.
              */
             int get_slot_by_pid(pid_t pid);
 
             /**
              * Count the slots in the particular state.
              * @param state the state.
              * @return the number of slots found.
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
@@ -43,97 +43,98 @@ class sitecing_parser : public sitecing_parserFlexLexer {
                 string path;
 
                 /**
                  * @param n the class name.
                  * @param p the component path.
                  */
                 ancestor_class(const string& n,const string& p)
                     : name(n), path(p) { }
         };
         /**
          * The list of ancestor classes.
          */
         typedef list<ancestor_class> ancestor_classes_t;
         /**
          * The ancestor classes.
          */
         ancestor_classes_t ancestor_classes;
         /**
          * The member variable definition.
          */
         class member_variable {
             public:
                 /**
                  * The member variable type.
                  */
                 string type;
                 /**
                  * The member variable name.
                  */
                 string name;
                 /**
                  * The member variable is a component.
                  */
                 bool bComponent;
                 /**
                  * The variable initializer.
                  */
                 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;
         /**
          * @todo TODO: wish I could remember the details -- document me.
          */
         bool have_initializers;
         /**
          * Whether the component has a constructor defined.
          */
         bool have_constructor;
         /**
          * Member function definition.
          */
         class member_function {
             public:
                 /**
                  * Return type.
                  */
                 string type;
                 /**
                  * Function name.
                  */
                 string name;
                 /**
                  * Arguments declaration.
                  */
                 string args;
                 /**
                  * Function body.
                  */
                 string body;
 
                 /**
                  * @param t type.
                  * @param n name.
                  * @param a arguments.
                  * @param b body.
                  */
@@ -176,98 +177,97 @@ class sitecing_parser : public sitecing_parserFlexLexer {
                     /**
                      * The number of modes.
                      */
                     modi
                 };
                 /**
                  * Processing flags enumeration.
                  */
                 enum {
                     /**
                      * Eat the comments.
                      */
                     flag_devour_comments   = 0x0001,
                     /**
                      * Eat whitespace.
                      */
                     flag_devour_whitespace = 0x0002
                 };
                 /**
                  * The processing mode.
                  */
                 modus_t modus;
                 /**
                  * The processing flags.
                  */
                 int flags;
                 /**
                  * Output being built.
                  */
                 string output;
                 /**
                  * The type for compound modes.
                  */
                 string _type;
                 /**
                  * The last id encountered.
                  */
                 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.
                  */
                 bool devour_whitespace() { return flags&flag_devour_whitespace; }
                 /**
                  * See if we're eating up the comments.
                  */
                 bool devour_comments() { return flags&flag_devour_comments; }
         };
         /**
          * The modes stack type.
          */
         typedef list<modus_operandi> modi_operandi;
         /**
          * The modes stack.
          */
         modi_operandi modi;
         /**
          * Input file name.
          */
         string input_file;
         /**
          * Base class name.
          */
         string base_class;
         /**
          * Base class header.
          */
         string base_header;
         /**
          * Component's basename.
          * @todo TODO: wish I could remember the details -- document me.
          */
         string component_basename;
         /**
          * The skeleton file name.
          */
         string skeleton;
         /**
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
@@ -1,94 +1,118 @@
 #ifndef __SITECING_SITECING_UTIL_H
 #define __SITECING_SITECING_UTIL_H
 
 #include <sys/types.h>
 #include <string>
 #include <konforka/exception.h>
 #include <konforka/util.h>
 
 /**
  * @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.
              */
             int fd;
 
             file_lock()
                 : fd(-1) { }
             /**
              * @param f file name.
              */
             file_lock(const string& f)
                 : fd(-1) { lock(f); }
             ~file_lock() { unlock(); }
 
             /**
              * Do lock.
              * @param f file name.
              */
             void lock(const string& f);
             /**
              * @todo TODO: wish I could remember the details -- document me.
              */
             void lock();
             /**
              * Release the lock obtained.
              */
             void unlock();
     };
 
     /**
      * The pid file. Removed at object destruction.
      */
     class pid_file {
         public:
             /**
              * The file name.
              */
             string file_name;
             /**
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
@@ -1,81 +1,81 @@
 #ifndef __SITECING_UTIL_H
 #define __SITECING_UTIL_H
 
 #include <ostream>
 #include <string>
 #include "sitecing/acomponent.h"
 
 /**
  * @file
  * @brief more or less non-internal utility classes and functions.
  */
 
 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);
 
     /**
      * The output string checkpoint object, letting one to rollback output.
      */
     class checkpoint {
         public:
             /**
              * The object's death will enumeration.
              */
             enum will_t {
                 /**
                  * The stream is to be rolled back at object destruction.
                  */
                 will_rollback,
                 /**
                  * The stream is not to be rolled back at object destruction.
                  */
                 will_commit,
                 /**
                  * The object will die intestate. What's the point then?
                  */
                 will_intestate
             };
             /**
              * The output stream in question.
              */
             ostream* stream;
             /**
              * The point at which objhect was created.
              */
             ostream::pos_type point;
             /**
              * The last will.
              */
             will_t last_will;
 
             /**