more comments

git-svn-id: http://svn.inspircd.org/repository/trunk/inspircd@10566 e03df62e-2008-0410-955e-edbf42e46eb7

3 files changed, 74 insertions, 7 deletions

diff --git a/include/caller.h b/include/caller.h
index 7c6565879..77fa5de40 100644
--- a/include/caller.h
+++ b/include/caller.h
@@ -14,7 +14,7 @@
 #ifndef __CALLER__H__
 #define __CALLER__H__
 
-/* The templates below can be auto generated by tools/create_templates.pl.
+/** The templates below can be auto generated by tools/create_templates.pl.
  * They are used to represent a functor with a given number of parameters and
  * a specific return type. To prevent passing the wrong number of parameters
  * and have the compiler detect this error at build-time, each class is numbered
@@ -47,7 +47,6 @@
  * this until you do, as if you get this wrong, this can generate some pretty long
  * winded and confusing error messages at compile time.
  */
-
 template <typename ReturnType> class CoreExport HandlerBase0
 {
  public:
@@ -253,7 +252,6 @@ template <typename ReturnType, typename Param1, typename Param2, typename Param3
  * The following parameters are the parameter types for Call(), and again, the macro is numbered to match the number of
  * parameters, to prevent mistakes.
  */
-
 #define DEFINE_HANDLER0(NAME, RETURN) \
 	class CoreExport NAME : public HandlerBase0<RETURN> { InspIRCd* Server; public: NAME(InspIRCd* Srv) : Server(Srv) { } virtual ~NAME() { } virtual RETURN Call(); }
 
diff --git a/include/channelmanager.h b/include/channelmanager.h
index c19876859..b5493529d 100644
--- a/include/channelmanager.h
+++ b/include/channelmanager.h
@@ -14,11 +14,17 @@
 #ifndef __CHANNELMANAGER_H
 #define __CHANNELMANAGER_H
 
+/** THe channel manager class allocates and deallocates channels and manages
+ * the container which holds them. For some reason, nobody finished this.
+ * TODO: Finish in future release!
+ */
 class CoreExport ChannelManager : public Extensible
 {
  private:
 	InspIRCd *ServerInstance;
  public:
+	/** Constructor
+	 */
 	ChannelManager(InspIRCd *Instance) : ServerInstance(Instance)
 	{
 	}
diff --git a/include/configreader.h b/include/configreader.h
index 029b8ac99..1bd6766be 100644
--- a/include/configreader.h
+++ b/include/configreader.h
@@ -149,6 +149,9 @@ typedef ValueContainer<char*> ValueContainerChar;
  */
 typedef ValueContainer<int*> ValueContainerInt;
 
+/** A specialization of ValueContainer to hold a pointer to
+ * a size_t.
+ */
 typedef ValueContainer<size_t*> ValueContainerST;
 
 /** A set of ValueItems used by multi-value validator functions
@@ -183,10 +186,18 @@ struct InitialConfig
 	Validator validation_function;
 };
 
+/** Represents a deprecated configuration tag.
+ */
 struct Deprecated
 {
+	/** Tag name
+	 */
 	const char* tag;
+	/** Tag value
+	 */
 	const char* value;
+	/** Reason for deprecation
+	 */
 	const char* reason;
 };
 
@@ -215,10 +226,18 @@ struct MultiConfig
  */
 typedef std::map<irc::string,char*> opertype_t;
 
+/** Holds an oper class.
+ */
 struct operclass_data : public Extensible
 {
+	/** Command list for the class
+	 */
 	char* commandlist;
+	/** Channel mode list for the class
+	 */
 	char* cmodelist;
+	/** User mode list for the class
+	 */
 	char* umodelist;
 };
 
@@ -226,21 +245,32 @@ struct operclass_data : public Extensible
  */
 typedef std::map<irc::string, operclass_data> operclass_t;
 
-
+/** Defines the server's length limits on various length-limited
+ * items such as topics, nicknames, channel names etc.
+ */
 class ServerLimits : public Extensible
 {
  public:
+	/** Maximum nickname length */
 	size_t NickMax;
+	/** Maximum channel length */
 	size_t ChanMax;
+	/** Maximum number of modes per line */
 	size_t MaxModes;
+	/** Maximum length of ident, not including ~ etc */
 	size_t IdentMax;
+	/** Maximum length of a quit message */
 	size_t MaxQuit;
+	/** Maximum topic length */
 	size_t MaxTopic;
+	/** Maximum kick message length */
 	size_t MaxKick;
+	/** Maximum GECOS (real name) length */
 	size_t MaxGecos;
+	/** Maximum away message length */
 	size_t MaxAway;
 
-	/* Creating the class initialises it to the defaults
+	/** Creating the class initialises it to the defaults
 	 * as in 1.1's ./configure script. Reading other values
 	 * from the config will change these values.
 	 */
@@ -248,6 +278,9 @@ class ServerLimits : public Extensible
 	{
 	}
 
+	/** Finalises the settings by adding one. This allows for them to be used as-is
+	 * without a 'value+1' when using the std::string assignment methods etc.
+	 */
 	void Finalise()
 	{
 		NickMax++;
@@ -299,14 +332,26 @@ class CoreExport ServerConfig : public Extensible
 	 */
 	bool DoInclude(ConfigDataHash &target, const std::string &file, std::ostringstream &errorstream);
 
+	/** User that is currently performing a rehash, needed because the
+	 * rehash code is now threaded and needs to know who to give errors and feedback to.
+	 */
 	User* RehashUser;
 
+	/** Rehash parameter, as above
+	 */
 	std::string RehashParameter;
 
+	/** Error stream, contains error output from any failed configuration parsing.
+	 */
 	std::ostringstream errstr;
 
+	/** Holds the new configuration when a rehash occurs so we dont overwrite the existing
+	 * working config with a broken one without checking it first and swapping pointers.
+	 */
 	ConfigDataHash newconfig;
 
+	/** Set of included files. Do we use this any more?
+	 */
 	std::map<std::string, std::istream*> IncludedFiles;
 
 	/** Used to indicate who we announce invites to on a channel */
@@ -315,8 +360,12 @@ class CoreExport ServerConfig : public Extensible
 	/** Pointer to function that validates dns server addresses (can be changed depending on platform) */
 	Validator DNSServerValidator;
 
+	/** Returns the creator InspIRCd pointer
+	 */
 	InspIRCd* GetInstance();
 
+	/** Not used any more as it is named, can probably be removed or renamed.
+	 */
 	int DoDownloads();
 	  
   	/** This holds all the information in the config file,
@@ -324,6 +373,8 @@ class CoreExport ServerConfig : public Extensible
 	 */
 	ConfigDataHash config_data;
 
+	/** Length limits, see definition of ServerLimits class
+	 */
 	ServerLimits Limits;
 
 	/** Clones CIDR range for ipv4 (0-32)
@@ -757,11 +808,10 @@ class CoreExport ServerConfig : public Extensible
 	 */
 	bool LoadConf(ConfigDataHash &target, FILE* &conf, const std::string &filename, std::ostringstream &errorstream);
 	
-	/* Both these return true if the value existed or false otherwise */
-	
 	/** Writes 'length' chars into 'result' as a string
 	 */
 	bool ConfValue(ConfigDataHash &target, const char* tag, const char* var, int index, char* result, int length, bool allow_linefeeds = false);
+
 	/** Writes 'length' chars into 'result' as a string
 	 */
 	bool ConfValue(ConfigDataHash &target, const char* tag, const char* var, const char* default_value, int index, char* result, int length, bool allow_linefeeds = false);
@@ -769,6 +819,7 @@ class CoreExport ServerConfig : public Extensible
 	/** Writes 'length' chars into 'result' as a string
 	 */
 	bool ConfValue(ConfigDataHash &target, const std::string &tag, const std::string &var, int index, std::string &result, bool allow_linefeeds = false);
+
 	/** Writes 'length' chars into 'result' as a string
 	 */
 	bool ConfValue(ConfigDataHash &target, const std::string &tag, const std::string &var, const std::string &default_value, int index, std::string &result, bool allow_linefeeds = false);
@@ -776,12 +827,15 @@ class CoreExport ServerConfig : public Extensible
 	/** Tries to convert the value to an integer and write it to 'result'
 	 */
 	bool ConfValueInteger(ConfigDataHash &target, const char* tag, const char* var, int index, int &result);
+
 	/** Tries to convert the value to an integer and write it to 'result'
 	 */
 	bool ConfValueInteger(ConfigDataHash &target, const char* tag, const char* var, const char* default_value, int index, int &result);
+
 	/** Tries to convert the value to an integer and write it to 'result'
 	 */
 	bool ConfValueInteger(ConfigDataHash &target, const std::string &tag, const std::string &var, int index, int &result);
+
 	/** Tries to convert the value to an integer and write it to 'result'
 	 */
 	bool ConfValueInteger(ConfigDataHash &target, const std::string &tag, const std::string &var, const std::string &default_value, int index, int &result);
@@ -789,12 +843,15 @@ class CoreExport ServerConfig : public Extensible
 	/** Returns true if the value exists and has a true value, false otherwise
 	 */
 	bool ConfValueBool(ConfigDataHash &target, const char* tag, const char* var, int index);
+
 	/** Returns true if the value exists and has a true value, false otherwise
 	 */
 	bool ConfValueBool(ConfigDataHash &target, const char* tag, const char* var, const char* default_value, int index);
+
 	/** Returns true if the value exists and has a true value, false otherwise
 	 */
 	bool ConfValueBool(ConfigDataHash &target, const std::string &tag, const std::string &var, int index);
+
 	/** Returns true if the value exists and has a true value, false otherwise
 	 */
 	bool ConfValueBool(ConfigDataHash &target, const std::string &tag, const std::string &var, const std::string &default_value, int index);
@@ -813,10 +870,16 @@ class CoreExport ServerConfig : public Extensible
 	 */
 	int ConfVarEnum(ConfigDataHash &target, const std::string &tag, int index);
 
+	/** Validates a hostname value, throwing ConfigException if it is not valid
+	 */
 	void ValidateHostname(const char* p, const std::string &tag, const std::string &val);
 
+	/** Validates an IP address value, throwing ConfigException if it is not valid
+	 */
 	void ValidateIP(const char* p, const std::string &tag, const std::string &val, bool wild);
 
+	/** Validates a value that should not contain spaces, throwing ConfigException of it is not valid
+	 */
 	void ValidateNoSpaces(const char* p, const std::string &tag, const std::string &val);
 
 	/** Returns the fully qualified path to the inspircd directory