Comment on a lot of recently added stuff that wasnt properly documented (until now)

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

4 files changed, 190 insertions, 8 deletions

diff --git a/include/ctables.h b/include/ctables.h
index 7d1173307..9eae05257 100644
--- a/include/ctables.h
+++ b/include/ctables.h
@@ -41,11 +41,14 @@ enum CmdResult
 #define CMD_LOCALONLY CMD_FAILURE
 
 
-/** A structure that defines a command
+/** A structure that defines a command. Every command available
+ * in InspIRCd must be defined as derived from command_t.
  */
 class command_t : public Extensible
 {
  protected:
+	/** Owner/Creator object
+	 */
 	InspIRCd* ServerInstance;
  public:
 	/** Command name
@@ -77,6 +80,16 @@ class command_t : public Extensible
 	 */
 	std::string syntax;
 
+	/** Create a new command.
+	 * @param Instance Pointer to creator class
+	 * @param cmd Command name. This must be UPPER CASE.
+	 * @param flags User modes required to execute the command.
+	 * For oper only commands, set this to 'o', otherwise use 0.
+	 * @param minpara Minimum parameters required for the command.
+	 * @param before_reg If this is set to true, the command will
+	 * be allowed before the user is 'registered' (has sent USER,
+	 * NICK, optionally PASS, and been resolved).
+	 */
 	command_t(InspIRCd* Instance, const std::string &cmd, char flags, int minpara, int before_reg = false) : ServerInstance(Instance), command(cmd), flags_needed(flags), min_params(minpara), disabled(false), works_before_reg(before_reg)
 	{
 		use_count = total_bytes = 0;
@@ -84,36 +97,74 @@ class command_t : public Extensible
 		syntax = "";
 	}
 
+	/** Handle the command from a user.
+	 * @param parameters The parameters for the command.
+	 * @param pcnt The number of parameters available in 'parameters'
+	 * @param user The user who issued the command.
+	 * @return Return CMD_SUCCESS on success, or CMD_FAILURE on failure.
+	 * If the command succeeds but should remain local to this server,
+	 * return CMD_LOCALONLY.
+	 */
 	virtual CmdResult Handle(const char** parameters, int pcnt, userrec* user) = 0;
 
+	/** Handle an internal request from another command, the core, or a module
+	 * @param Command ID
+	 * @param Zero or more parameters, whos form is specified by the command ID.
+	 * @return Return CMD_SUCCESS on success, or CMD_FAILURE on failure.
+	 * If the command succeeds but should remain local to this server,
+	 * return CMD_LOCALONLY.
+	 */
 	virtual CmdResult HandleInternal(const unsigned int id, const std::deque<classbase*> &params)
 	{
 		return CMD_INVALID;
 	}
 
+	/** Handle the command from a server.
+	 * Not currently used in this version of InspIRCd.
+	 * @param parameters The parameters given
+	 * @param pcnt The number of parameters available
+	 * @param servername The server name which issued the command
+	 * @return Return CMD_SUCCESS on success, or CMD_FAILURE on failure.
+	 * If the command succeeds but should remain local to this server,
+	 * return CMD_LOCALONLY.
+	 */
 	virtual CmdResult HandleServer(const char** parameters, int pcnt, const std::string &servername)
 	{
 		return CMD_INVALID;
 	}
 
+	/** Disable or enable this command.
+	 * @param setting True to disable the command.
+	 */
 	void Disable(bool setting)
 	{
 		disabled = setting;
 	}
 
+	/** Obtain this command's disable state.
+	 * @return true if the command is currently disabled
+	 * (disabled commands can be used only by operators)
+	 */
 	bool IsDisabled()
 	{
 		return disabled;
 	}
 
+	/** @return true if the command works before registration.
+	 */
 	bool WorksBeforeReg()
 	{
 		return works_before_reg;
 	}
 
+	/** Standard constructor gubbins
+	 */
 	virtual ~command_t() {}
 };
 
+/** A hash of commands used by the core
+ */
 typedef nspace::hash_map<std::string,command_t*> command_table;
 
 #endif
+
diff --git a/include/dns.h b/include/dns.h
index 562a49322..6913527ae 100644
--- a/include/dns.h
+++ b/include/dns.h
@@ -55,11 +55,25 @@ class Module;
 class DNSResult : public classbase
 {
  public:
+	/** Result ID
+	 */
 	int id;
+	/** Result body, a hostname or IP address
+	 */
 	std::string result;
+	/** Time-to-live value of the result
+	 */
 	unsigned long ttl;
+	/** The original request, a hostname or IP address
+	 */
 	std::string original;
 
+	/** Build a DNS result.
+	 * @param i The request ID
+	 * @param res The request result, a hostname or IP
+	 * @param timetolive The request time-to-live
+	 * @param orig The original request, a hostname or IP
+	 */
 	DNSResult(int i, const std::string &res, unsigned long timetolive, const std::string &orig) : id(i), result(res), ttl(timetolive), original(orig) { }
 };
 
@@ -68,19 +82,30 @@ class DNSResult : public classbase
  */
 typedef std::pair<unsigned char*, std::string> DNSInfo;
 
-/** Cached item
+/** Cached item stored in the query cache.
  */
 class CachedQuery
 {
  public:
+	/** The cached result data, an IP or hostname
+	 */
 	std::string data;
+	/** The time when the item is due to expire
+	 */
 	time_t expires;
 
+	/** Build a cached query
+	 * @param res The result data, an IP or hostname
+	 * @param ttl The time-to-live value of the query result
+	 */
 	CachedQuery(const std::string &res, unsigned int ttl) : data(res)
 	{
 		expires = time(NULL) + ttl;
 	}
 
+	/** Returns the number of seconds remaining before this
+	 * cache item has expired and should be removed.
+	 */
 	int CalcTTLRemaining()
 	{
 		int n = expires - time(NULL);
@@ -88,7 +113,7 @@ class CachedQuery
 	}
 };
 
-/** DNS cache information
+/** DNS cache information. Holds IPs mapped to hostnames, and hostnames mapped to IPs.
  */
 typedef nspace::hash_map<irc::string, CachedQuery, nspace::hash<irc::string> > dnscache;
 
@@ -277,12 +302,15 @@ class Resolver : public Extensible
 	 * this method will return -1.
 	 */
 	int GetId();
-
 	/**
 	 * Returns the creator module, or NULL
 	 */
 	Module* GetCreator();
-
+	/**
+	 * If the result is a cached result, this triggers the objects
+	 * OnLookupComplete. This is done because it is not safe to call
+	 * the abstract virtual method from the constructor.
+	 */
 	void TriggerCachedResult();
 };
 
@@ -295,6 +323,9 @@ class DNS : public EventHandler
 {
  private:
 
+	/**
+	 * Creator/Owner object
+	 */
 	InspIRCd* ServerInstance;
 
 	/**
@@ -326,6 +357,9 @@ class DNS : public EventHandler
 	 */
 	dnscache* cache;
 
+	/** A timer which ticks every hour to remove expired
+	 * items from the DNS cache.
+	 */
 	class CacheTimer* PruneTimer;
 
 	/**
@@ -334,14 +368,17 @@ class DNS : public EventHandler
 	int MakePayload(const char* name, const QueryType rr, const unsigned short rr_class, unsigned char* payload);
 
  public:
+
 	/**
 	 * Currently active Resolver classes
 	 */
 	Resolver* Classes[MAX_REQUEST_ID];
+
 	/**
 	 * Requests that are currently 'in flight'
 	 */
 	DNSRequest* requests[MAX_REQUEST_ID];
+
 	/**
 	 * The port number DNS requests are made on,
 	 * and replies have as a source-port number.
@@ -352,14 +389,17 @@ class DNS : public EventHandler
 	 * Fill an rr (resource record) with data from input
 	 */
 	static void FillResourceRecord(ResourceRecord* rr, const unsigned char* input);
+
 	/**
 	 * Fill a header with data from input limited by a length
 	 */
 	static void FillHeader(DNSHeader *header, const unsigned char *input, const int length);
+
 	/**
 	 * Empty out a header into a data stream ready for transmission "on the wire"
 	 */
 	static void EmptyHeader(unsigned char *output, const DNSHeader *header, const int length);
+
 	/**
 	 * Start the lookup of an ipv4 from a hostname
 	 */
@@ -447,11 +487,26 @@ class DNS : public EventHandler
 	 */
 	void CleanResolvers(Module* module);
 
+	/** Return the cached value of an IP or hostname
+	 * @param source An IP or hostname to find in the cache.
+	 * @return A pointer to a CachedQuery if the item exists,
+	 * otherwise NULL.
+	 */
 	CachedQuery* GetCache(const std::string &source);
 
+	/** Delete a cached item from the DNS cache.
+	 * @param source An IP or hostname to remove
+	 */
 	void DelCache(const std::string &source);
 
+	/** Clear all items from the DNS cache immediately.
+	 */
 	int ClearCache();
+
+	/** Prune the DNS cache, e.g. remove all expired
+	 * items and rehash the cache buckets, but leave
+	 * items in the hash which are still valid.
+	 */
 	int PruneCache();
 };
 
diff --git a/include/timer.h b/include/timer.h
index 9820be2fb..2d12d84e5 100644
--- a/include/timer.h
+++ b/include/timer.h
@@ -30,7 +30,11 @@ class InspTimer : public Extensible
 	/** The triggering time
 	 */
 	time_t trigger;
+	/** Number of seconds between triggers
+	 */
 	long secs;
+	/** True if this is a repeating timer
+	 */
 	bool repeat;
  public:
 	/** Default constructor, initializes the triggering time
@@ -44,29 +48,49 @@ class InspTimer : public Extensible
 		secs = secs_from_now;
 		repeat = repeating;
 	}
+
 	/** Default destructor, does nothing.
 	 */
 	virtual ~InspTimer() { }
+
 	/** Retrieve the current triggering time
 	 */
 	virtual time_t GetTimer()
 	{
 		return trigger;
 	}
+
 	/** Called when the timer ticks.
+	 * You should override this method with some useful code to
+	 * handle the tick event.
 	 */
 	virtual void Tick(time_t TIME) = 0;
 
+	/** Returns true if this timer is set to repeat
+	 */
 	bool GetRepeat()
 	{
 		return repeat;
 	}
 
+	/** Returns the interval (number of seconds between ticks)
+	 * of this timer object.
+	 */
 	long GetSecs()
 	{
 		return secs;
 	}
 
+	/** Cancels the repeat state of a repeating timer.
+	 * If you call this method, then the next time your
+	 * timer ticks, it will be removed immediately after.
+	 * You should use this method call to remove a recurring
+	 * timer if you wish to do so within the timer's Tick
+	 * event, as calling TimerManager::DelTimer() from within
+	 * the InspTimer::Tick() method is dangerous and may
+	 * cause a segmentation fault. Calling CancelRepeat()
+	 * is safe in this case.
+	 */
 	void CancelRepeat()
 	{
 		repeat = false;
diff --git a/include/users.h b/include/users.h
index d69781f80..bfe21f116 100644
--- a/include/users.h
+++ b/include/users.h
@@ -120,68 +120,107 @@ class ConnectClass : public classbase
 
 public:
 
+	/** Create a new connect class with no settings.
+	 */
 	ConnectClass() : type(CC_DENY), registration_timeout(0), flood(0), host(""), pingtime(0), pass(""),
 			threshold(0), sendqmax(0), recvqmax(0), maxlocal(0), maxglobal(0) { }
 
+	/** Create a new connect class to ALLOW connections.
+	 * @param timeout The registration timeout
+	 * @param fld The flood value
+	 * @param hst The IP mask to allow
+	 * @param ping The ping frequency
+	 * @param pas The password to be used
+	 * @param thres The flooding threshold
+	 * @param sendq The maximum sendq value
+	 * @param recvq The maximum recvq value
+	 * @param maxl The maximum local sessions
+	 * @param maxg The maximum global sessions
+	 */
 	ConnectClass(unsigned int timeout, unsigned int fld, const std::string &hst, unsigned int ping,
 			const std::string &pas, unsigned int thres, unsigned long sendq, unsigned long recvq,
 			unsigned long maxl, unsigned long maxg) :
 			type(CC_ALLOW), registration_timeout(timeout), flood(fld), host(hst), pingtime(ping), pass(pas),
 			threshold(thres), sendqmax(sendq), recvqmax(recvq), maxlocal(maxl), maxglobal(maxg) { }
 
+	/** Create a new connect class to DENY  connections
+	 * @param hst The IP mask to deny
+	 */
 	ConnectClass(const std::string &hst) : type(CC_DENY), registration_timeout(0), flood(0), host(hst), pingtime(0),
 			pass(""), threshold(0), sendqmax(0), recvqmax(0), maxlocal(0), maxglobal(0) { }
 
+	/** Returns the type, CC_ALLOW or CC_DENY
+	 */
 	char GetType()
 	{
 		return (type == CC_ALLOW ? CC_ALLOW : CC_DENY);
 	}
 
+	/** Returns the registration timeout
+	 */
 	unsigned int GetRegTimeout()
 	{
 		return (registration_timeout ? registration_timeout : 90);
 	}
 
+	/** Returns the flood limit
+	 */
 	unsigned int GetFlood()
 	{
 		return (threshold ? flood : 999);
 	}
 
+	/** Returns the allowed or denied IP mask
+	 */
 	const std::string& GetHost()
 	{
 		return host;
 	}
 
+	/** Returns the ping frequency
+	 */
 	unsigned int GetPingTime()
 	{
 		return (pingtime ? pingtime : 120);
 	}
 
+	/** Returns the password or an empty string
+	 */
 	const std::string& GetPass()
 	{
 		return pass;
 	}
 
+	/** Returns the flood threshold value
+	 */
 	unsigned int GetThreshold()
 	{
 		return (threshold ? threshold : 1);
 	}
 
+	/** Returns the maximum sendq value
+	 */
 	unsigned long GetSendqMax()
 	{
 		return (sendqmax ? sendqmax : 262114);
 	}
 
+	/** Returns the maximum recvq value
+	 */
 	unsigned long GetRecvqMax()
 	{
 		return (recvqmax ? recvqmax : 4096);
 	}
 
+	/** Returusn the maximum number of local sessions
+	 */
 	unsigned long GetMaxLocal()
 	{
 		return (maxlocal ? maxlocal : 1);
 	}
 
+	/** Returns the maximum number of global sessions
+	 */
 	unsigned long GetMaxGlobal()
 	{
 		return (maxglobal ? maxglobal : 1);
@@ -227,8 +266,16 @@ class userrec : public connection
 	 */
 	unsigned int ChannelCount;
 
+	/** Cached nick!ident@host value using the real hostname
+	 */
 	char* cached_fullhost;
+
+	/** Cached nick!ident@ip value using the real IP address
+	 */
 	char* cached_hostip;
+
+	/** Cached nick!ident@host value using the masked hostname
+	 */
 	char* cached_makehost;
 	char* cached_fullrealhost;
 
@@ -368,7 +415,8 @@ class userrec : public connection
 	 */
 	long threshold;
 
-	/** IPV4 or IPV6 ip address
+	/** IPV4 or IPV6 ip address. Use SetSockAddr to set this and GetProtocolFamily/
+	 * GetIPString/GetPort to obtain its values.
 	 */
 	sockaddr* ip;
 
@@ -404,11 +452,13 @@ class userrec : public connection
 	 */
 	std::string WriteError;
 
-	/** Maximum size this user's sendq can become
+	/** Maximum size this user's sendq can become.
+	 * Copied from the connect class on connect.
 	 */
 	long sendqmax;
 
-	/** Maximum size this user's recvq can become
+	/** Maximum size this user's recvq can become.
+	 * Copied from the connect class on connect.
 	 */
 	long recvqmax;
 
@@ -838,6 +888,8 @@ class userrec : public connection
 
 	/** Handle socket event.
 	 * From EventHandler class.
+	 * @param et Event type
+	 * @param errornum Error number for EVENT_ERROR events
 	 */
 	void HandleEvent(EventType et, int errornum = 0);