Commented a lot of stuff that hasnt been commented since 1.0.2

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

6 files changed, 120 insertions, 41 deletions

diff --git a/include/channels.h b/include/channels.h
index 65f3948fe..2445d1188 100644
--- a/include/channels.h
+++ b/include/channels.h
@@ -24,6 +24,8 @@
 #include <string>
 #include <map>
 
+/** RFC1459 channel modes
+ */
 enum ChannelModes {
 	CM_TOPICLOCK = 't'-65,
 	CM_NOEXTERNAL = 'n'-65,
@@ -51,25 +53,18 @@ class HostItem : public classbase
 	virtual ~HostItem() { /* stub */ }
 };
 
-// banlist is inherited from HostList mainly for readability
-// reasons only
-
 /** A subclass of HostItem designed to hold channel bans (+b)
  */
 class BanItem : public HostItem
 {
 };
 
-// same with this...
-
 /** A subclass of HostItem designed to hold channel exempts (+e)
  */
 class ExemptItem : public HostItem
 {
 };
 
-// and this...
-
 /** A subclass of HostItem designed to hold channel invites (+I)
  */
 class InviteItem : public HostItem
@@ -88,8 +83,6 @@ typedef std::vector<ExemptItem>	ExemptList;
  */
 typedef std::vector<InviteItem>	InviteList;
 
-class userrec;
-
 /** A list of users on a channel
  */
 typedef std::map<userrec*,userrec*> CUList;
@@ -108,10 +101,13 @@ class chanrec : public Extensible
 	/** The channels name.
 	 */
 	char name[CHANMAX]; /* channel name */
-	/** Custom modes for the channel.
-	 * Plugins may use this field in any way they see fit.
+	/** Modes for the channel.
+	 * This is not a null terminated string! It is a hash where
+	 * each item in it represents if a mode is set. For example
+	 * for mode +A, index 0. Use modechar-65 to calculate which
+	 * field to check.
 	 */
-	char modes[64];     /* modes handled by modules */
+	char modes[64];
 
 	/** User lists
 	 * There are four user lists, one for 
@@ -222,7 +218,7 @@ class chanrec : public Extensible
 	void DelHalfoppedUser(userrec* user);
 	void DelVoicedUser(userrec* user);
 
-	/** Obrain the internal reference list
+	/** Obtain the internal reference list
 	 * The internal reference list contains a list of userrec*.
 	 * These are used for rapid comparison to determine
 	 * channel membership for PRIVMSG, NOTICE, QUIT, PART etc.
@@ -236,12 +232,16 @@ class chanrec : public Extensible
 	CUList* GetHalfoppedUsers();
 	CUList* GetVoicedUsers();
 
+	/** Returns true if the user given is on the given channel.
+	 */
 	bool HasUser(userrec* user);
 
 	/** Creates a channel record and initialises it with default values
 	 */
 	chanrec();
 
+	/** Destructor for chanrec
+	 */
 	virtual ~chanrec() { /* stub */ }
 };
 
@@ -271,7 +271,12 @@ class ucrec : public classbase
 	 */
 	chanrec *channel;
 
+	/** Constructor for ucrec
+	 */
 	ucrec() : uc_modes(0), channel(NULL) { /* stub */ }
+
+	/** Destructor for ucrec
+	 */
 	virtual ~ucrec() { /* stub */ }
 };
 
diff --git a/include/modules.h b/include/modules.h
index 1f73d3983..88d4eecdf 100644
--- a/include/modules.h
+++ b/include/modules.h
@@ -87,10 +87,11 @@ typedef file_cache string_list;
 typedef std::deque<userrec*> chanuserlist;
 
 
-// This #define allows us to call a method in all
-// loaded modules in a readable simple way, e.g.:
-// 'FOREACH_MOD OnConnect(user);'
-
+/**
+ * This #define allows us to call a method in all
+ * loaded modules in a readable simple way, e.g.:
+ * 'FOREACH_MOD(I_OnXonnwxr,OnConnect(user));'
+ */
 #define FOREACH_MOD(y,x) if (Config->global_implementation[y] > 0) { \
 	for (int _i = 0; _i <= MODCOUNT; _i++) { \
 	if (Config->implement_lists[_i][y]) \
@@ -105,12 +106,11 @@ typedef std::deque<userrec*> chanuserlist;
 	} \
   }
 
-// This define is similar to the one above but returns a result in MOD_RESULT.
-// The first module to return a nonzero result is the value to be accepted,
-// and any modules after are ignored.
-
-// *********************************************************************************************
-
+/**
+ *  This define is similar to the one above but returns a result in MOD_RESULT.
+ * The first module to return a nonzero result is the value to be accepted,
+ * and any modules after are ignored.
+ */
 #define FOREACH_RESULT(y,x) { if (Config->global_implementation[y] > 0) { \
 			MOD_RESULT = 0; \
 			for (int _i = 0; _i <= MODCOUNT; _i++) { \
@@ -131,8 +131,6 @@ typedef std::deque<userrec*> chanuserlist;
 		} \
 	} \
  }
-   
-// *********************************************************************************************
 
 #define FD_MAGIC_NUMBER -42
 
@@ -142,12 +140,6 @@ typedef std::deque<userrec*> chanuserlist;
 #define IS_REMOTE(x) (x->fd < 0)
 #define IS_MODULE_CREATED(x) (x->fd == FD_MAGIC_NUMBER)
 
-/*extern void createcommand(char* cmd, handlerfunc f, char flags, int minparams, char* source);
-extern void server_mode(char **parameters, int pcnt, userrec *user);*/
-
-// class Version holds the version information of a Module, returned
-// by Module::GetVersion (thanks RD)
-
 /** Holds a module's Version information
  *  The four members (set by the constructor only) indicate details as to the version number
  *  of a module. A class of type Version is returned by the GetVersion method of the Module class.
@@ -171,13 +163,9 @@ class Admin : public classbase
 	 Admin(std::string name, std::string email, std::string nick);
 };
 
-
 // Forward-delacare module for ModuleMessage etc
 class Module;
 
-// Thanks to Rob (from anope) for the idea of this message passing API
-// (its been done before, but this seemed a very neat and tidy way...
-
 /** The ModuleMessage class is the base class of Request and Event
  * This class is used to represent a basic data structure which is passed
  * between modules for safe inter-module communications.
@@ -342,7 +330,7 @@ enum Implementation {	I_OnUserConnect, I_OnUserQuit, I_OnUserDisconnect, I_OnUse
 /** Base class for all InspIRCd modules
  *  This class is the base class for InspIRCd modules. All modules must inherit from this class,
  *  its methods will be called when irc server events occur. class inherited from module must be
- *  instantiated by the ModuleFactory class (see relevent section) for the plugin to be initialised.
+ *  instantiated by the ModuleFactory class (see relevent section) for the module to be initialised.
  */
 class Module : public classbase
 {
@@ -1248,8 +1236,14 @@ class Module : public classbase
 	 */
 	virtual int OnRawSocketRead(int fd, char* buffer, unsigned int count, int &readresult);
 
+	/** Called whenever a user sets away.
+	 * This method has no parameter for the away message, as it is available in the
+	 * user record as userrec::awaymsg.
+	 */
 	virtual void OnSetAway(userrec* user);
 
+	/** Called when a user cancels their away state.
+	 */
 	virtual void OnCancelAway(userrec* user);
 };
 
@@ -1739,12 +1733,27 @@ class Server : public classbase
 	 */
 	virtual void DelSocket(InspSocket* sock);
 
+	/** Causes the local server to rehash immediately.
+	 * WARNING: Do not call this method from within your rehash method, for
+	 * obvious reasons!
+	 */
 	virtual void RehashServer();
 
+	/** This method returns the total number of channels on the network.
+	 */
 	virtual long GetChannelCount();
 
+	/** This method returns a channel whos index is greater than or equal to 0 and less than the number returned by Server::GetChannelCount().
+	 * This is slower (by factors of dozens) than requesting a channel by name with Server::FindChannel(), however there are times when
+	 * you wish to safely iterate the channel list, saving your position, with large amounts of time in between, which is what this function
+	 * is useful for.
+	 */
 	virtual chanrec* GetChannelIndex(long index);
 
+	/** Dumps text (in a stringstream) to a user. The stringstream should not contain linefeeds, as it will be split
+	 * automatically by the function into safe amounts. The line prefix given is prepended onto each line (e.g. a servername
+	 * and a numeric).
+	 */
 	void DumpText(userrec* User, const std::string &LinePrefix, stringstream &TextStream);
 };
 
@@ -1852,6 +1861,8 @@ class ConfigReader : public classbase
  */
 class FileReader : public classbase
 {
+	/** The file contents
+	 */
 	file_cache fc;
  public:
 	 /** Default constructor.
diff --git a/include/socket.h b/include/socket.h
index 3a5036706..4ac7eecea 100644
--- a/include/socket.h
+++ b/include/socket.h
@@ -140,8 +140,18 @@ private:
 	 */
 	bool FlushWriteBuffer();
 
+	/** Set the queue sizes
+	 * This private method sets the operating system queue
+	 * sizes for this socket to 65535 so that it can queue
+	 * more information without application-level queueing
+	 * which was required in older software.
+	 */
 	void SetQueues(int nfd);
 
+	/** When the socket has been marked as closing, this flag
+	 * will be set to true, then the next time the socket is
+	 * examined, the socket is deleted and closed.
+	 */
 	bool ClosePending;
 
 public:
@@ -320,9 +330,27 @@ public:
 	 */
 	virtual ~InspSocket();
 
+	/**
+	 * This method attempts to resolve the hostname,
+	 * if a hostname is given and not an IP,
+	 * before a connection can occur. This method is
+	 * asyncronous.
+	 */
 	virtual bool DoResolve();
+
+	/**
+	 * This method attempts to connect to a hostname.
+	 * This only occurs on a non-listening socket. This
+	 * method is asyncronous.
+	 */
 	virtual bool DoConnect();
 
+	/**
+	 * This method marks the socket closed.
+	 * The next time the core examines a socket marked
+	 * as closed, the socket will be closed and the 
+	 * memory reclaimed.
+	 */
 	void MarkAsClosed();
 };
 
diff --git a/include/socketengine.h b/include/socketengine.h
index f2679811e..23fbd8d68 100644
--- a/include/socketengine.h
+++ b/include/socketengine.h
@@ -138,6 +138,9 @@ public:
 	 */
 	bool DelFd(int fd);
 
+	/** Returns true if a socket exists in the socket
+	 * engine's list.
+	 */
 	bool HasFd(int fd);
 
 	/** Waits for an event.
diff --git a/include/timer.h b/include/timer.h
index b75f3776f..3c4fb0897 100644
--- a/include/timer.h
+++ b/include/timer.h
@@ -14,23 +14,41 @@
  * ---------------------------------------------------
  */
 
+/** Timer class for one-second resolution timers
+ * InspTimer provides a facility which allows module
+ * developers to create one-shot timers. The timer
+ * can be made to trigger at any time up to a one-second
+ * resolution. To use InspTimer, inherit a class from
+ * InspTimer, then insert your inherited class into the
+ * queue using Server::AddTimer(). The Tick() method of
+ * your object (which you should override) will be called
+ * at the given time.
+ */
 class InspTimer
 {
  private:
+	/** The triggering time
+	 */
 	time_t trigger;
  public:
+	/** Default constructor, initializes the triggering time
+	 */
 	InspTimer(long secs_from_now,time_t now)
 	{
 		trigger = now + secs_from_now;
 	}
+	/** Default destructor, does nothing.
+	 */
 	virtual ~InspTimer() { }
+	/** Retrieve the current triggering time
+	 */
 	virtual time_t GetTimer()
 	{
 		return trigger;
 	}
-	virtual void Tick(time_t TIME)
-	{
-	}
+	/** Called when the timer ticks.
+	 */
+	virtual void Tick(time_t TIME) = 0;
 };
 
 void TickTimers(time_t TIME);
diff --git a/include/users.h b/include/users.h
index dfd5c5e89..a5cba44b6 100644
--- a/include/users.h
+++ b/include/users.h
@@ -237,6 +237,8 @@ class userrec : public connection
 	 */
 	long recvqmax;
 
+	/** Default constructor
+	 */
 	userrec();
 	
 	/** Returns the full displayed host of the user
@@ -334,21 +336,33 @@ class userrec : public connection
 	 */
 	InvitedList* GetInviteList();
 
-	void MakeHost(char* nhost);
-
+	/** Creates a wildcard host.
+	 * Takes a buffer to use and fills the given buffer with the host in the format *!*@hostname
+	 */
 	char* MakeWildHost();
 
+	/** Creates a host.
+	 * Takes a buffer to use and fills the given buffer with the host in the format nick!user@host
+	 */
+	void MakeHost(char* nhost);
+
 	/** Shuts down and closes the user's socket
 	 */
 	void CloseSocket();
 
+	/** Default destructor
+	 */
 	virtual ~userrec();
 
 #ifdef THREADED_DNS
+	/** Thread used for threaded lookups
+	 */
 	pthread_t dnsthread;
 #endif
 };
 
+/** Used to hold WHOWAS information
+ */
 class WhoWasGroup
 {
  public: