Comments only.

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

4 files changed, 156 insertions, 22 deletions

diff --git a/src/modules/m_spanningtree/rconnect.h b/src/modules/m_spanningtree/rconnect.h
index 08c7592d2..271c93f6c 100644
--- a/src/modules/m_spanningtree/rconnect.h
+++ b/src/modules/m_spanningtree/rconnect.h
@@ -5,8 +5,8 @@
  */
 class cmd_rconnect : public command_t
 {
-        Module* Creator;
-        SpanningTreeUtilities* Utils;
+        Module* Creator;		/* Creator */
+        SpanningTreeUtilities* Utils;	/* Utility class */
  public:
         cmd_rconnect (InspIRCd* Instance, Module* Callback, SpanningTreeUtilities* Util);
         CmdResult Handle (const char** parameters, int pcnt, userrec *user);
diff --git a/src/modules/m_spanningtree/treeserver.h b/src/modules/m_spanningtree/treeserver.h
index 716369f5b..8ce7ae041 100644
--- a/src/modules/m_spanningtree/treeserver.h
+++ b/src/modules/m_spanningtree/treeserver.h
@@ -64,27 +64,84 @@ class TreeServer : public classbase
 	 */
 	void DelHashEntry();
 
-	/** These accessors etc should be pretty self-
-	 * explanitory.
+	/** Get route.
+	 * The 'route' is defined as the locally-
+	 * connected server which can be used to reach this server.
 	 */
 	TreeServer* GetRoute();
+
+	/** Get server name
+	 */
 	std::string GetName();
+
+	/** Get server description (GECOS)
+	 */
 	std::string GetDesc();
+
+	/** Get server version string
+	 */
 	std::string GetVersion();
+
+	/** Set time we are next due to ping this server
+	 */
 	void SetNextPingTime(time_t t);
+
+	/** Get the time we are next due to ping this server
+	 */
 	time_t NextPingTime();
+
+	/** True if the server answered their last ping
+	 */
 	bool AnsweredLastPing();
+
+	/** Set the server as responding to its last ping
+	 */
 	void SetPingFlag();
+
+	/** Get the number of users on this server for MAP
+	 */
 	int GetUserCount();
+
+	/** Increment the user counter
+	 */
 	void AddUserCount();
+
+	/** Decrement the user counter
+	 */
 	void DelUserCount();
+
+	/** Get the oper count for this server
+	 */
 	int GetOperCount();
+
+	/** Get the TreeSocket pointer for local servers.
+	 * For remote servers, this returns NULL.
+	 */
 	TreeSocket* GetSocket();
+
+	/** Get the parent server.
+	 * For the root node, this returns NULL.
+	 */
 	TreeServer* GetParent();
+
+	/** Set the server version string
+	 */
 	void SetVersion(const std::string &Version);
+
+	/** Return number of child servers
+	 */
 	unsigned int ChildCount();
+
+	/** Return a child server indexed 0..n
+	 */
 	TreeServer* GetChild(unsigned int n);
+
+	/** Add a child server
+	 */
 	void AddChild(TreeServer* Child);
+
+	/** Delete a child server, return false if it didn't exist.
+	 */
 	bool DelChild(TreeServer* Child);
 
 	/** Removes child nodes of this node, and of that node, etc etc.
@@ -93,6 +150,8 @@ class TreeServer : public classbase
 	 */
 	bool Tidy();
 
+	/** Destructor
+	 */
 	~TreeServer();
 
 };
diff --git a/src/modules/m_spanningtree/treesocket.h b/src/modules/m_spanningtree/treesocket.h
index 24b250dba..52496a4ef 100644
--- a/src/modules/m_spanningtree/treesocket.h
+++ b/src/modules/m_spanningtree/treesocket.h
@@ -64,21 +64,21 @@ enum ServerState { LISTENER, CONNECTING, WAIT_AUTH_1, WAIT_AUTH_2, CONNECTED };
  */
 class TreeSocket : public InspSocket
 {
-	SpanningTreeUtilities* Utils;
-	std::string myhost;
-	std::string in_buffer;
-	ServerState LinkState;
-	std::string InboundServerName;
-	std::string InboundDescription;
-	int num_lost_users;
-	int num_lost_servers;
-	time_t NextPing;
-	bool LastPingWasGood;
-	bool bursting;
-	unsigned int keylength;
-	std::string ModuleList;
-	std::map<std::string,std::string> CapKeys;
-	Module* Hook;
+	SpanningTreeUtilities* Utils;		/* Utility class */
+	std::string myhost;			/* Canonical hostname */
+	std::string in_buffer;			/* Input buffer */
+	ServerState LinkState;			/* Link state */
+	std::string InboundServerName;		/* Server name sent to us by other side */
+	std::string InboundDescription;		/* Server description (GECOS) sent to us by the other side */
+	int num_lost_users;			/* Users lost in split */
+	int num_lost_servers;			/* Servers lost in split */
+	time_t NextPing;			/* Time when we are due to ping this server */
+	bool LastPingWasGood;			/* Responded to last ping we sent? */
+	bool bursting;				/* True if not finished bursting yet */
+	unsigned int keylength;			/* Is this still used? */
+	std::string ModuleList;			/* Module list of other server from CAPAB */
+	std::map<std::string,std::string> CapKeys;	/* CAPAB keys from other server */
+	Module* Hook;				/* I/O hooking module that we're attached to for this socket */
 
  public:
 
@@ -89,6 +89,11 @@ class TreeSocket : public InspSocket
 	 */
 	TreeSocket(SpanningTreeUtilities* Util, InspIRCd* SI, std::string host, int port, bool listening, unsigned long maxtime, Module* HookMod = NULL);
 
+	/** Because most of the I/O gubbins are encapsulated within
+	 * InspSocket, we just call the superclass constructor for
+	 * most of the action, and append a few of our own values
+	 * to it.
+	 */
 	TreeSocket(SpanningTreeUtilities* Util, InspIRCd* SI, std::string host, int port, bool listening, unsigned long maxtime, const std::string &ServerName, const std::string &bindto, Module* HookMod = NULL);
 
 	/** When a listening socket gives us a new file descriptor,
@@ -97,10 +102,16 @@ class TreeSocket : public InspSocket
 	 */
 	TreeSocket(SpanningTreeUtilities* Util, InspIRCd* SI, int newfd, char* ip, Module* HookMod = NULL);
 
+	/** Get link state
+	 */
 	ServerState GetLinkState();
 
+	/** Return the module which we are hooking to for I/O encapsulation
+	 */
 	Module* GetHook();
 
+	/** Destructor
+	 */
 	~TreeSocket();
 
 	/** When an outbound connection finishes connecting, we receive
@@ -111,8 +122,12 @@ class TreeSocket : public InspSocket
 	 */
 	virtual bool OnConnected();
 
+	/** Handle socket error event
+	 */
 	virtual void OnError(InspSocketError e);
 
+	/** Handle socket disconnect event
+	 */
 	virtual int OnDisconnect();
 
 	/** Recursively send the server tree with distances as hops.
@@ -126,8 +141,12 @@ class TreeSocket : public InspSocket
 	 */
 	void SendServers(TreeServer* Current, TreeServer* s, int hops);
 
+	/** Returns my capabilities as a string
+	 */
 	std::string MyCapabilities();
 
+	/** Send my capabilities to the remote side
+	 */
 	void SendCapabilities();
 
 	/* Check a comma seperated list for an item */
@@ -196,9 +215,11 @@ class TreeSocket : public InspSocket
 	 */
 	virtual bool OnDataReady();
 
+	/** Send one or more complete lines down the socket
+	 */
 	int WriteLine(std::string line);
 
-	/* Handle ERROR command */
+	/** Handle ERROR command */
 	bool Error(std::deque<std::string> &params);
 
 	/** remote MOTD. leet, huh? */
@@ -219,60 +240,109 @@ class TreeSocket : public InspSocket
 	 */
 	bool ForceNick(const std::string &prefix, std::deque<std::string> &params);
 
-	/*
-	 * Remote SQUIT (RSQUIT). Routing works similar to SVSNICK: Route it to the server that the target is connected to locally,
+	/** Remote SQUIT (RSQUIT). Routing works similar to SVSNICK: Route it to the server that the target is connected to locally,
 	 * then let that server do the dirty work (squit it!). Example:
 	 * A -> B -> C -> D: oper on A squits D, A routes to B, B routes to C, C notices D connected locally, kills it. -- w00t
 	 */
 	bool RemoteSquit(const std::string &prefix, std::deque<std::string> &params);
 
+	/** SVSJOIN
+	 */
 	bool ServiceJoin(const std::string &prefix, std::deque<std::string> &params);
 
+	/** REHASH
+	 */
 	bool RemoteRehash(const std::string &prefix, std::deque<std::string> &params);
 
+	/** KILL
+	 */
 	bool RemoteKill(const std::string &prefix, std::deque<std::string> &params);
 
+	/** PONG
+	 */
 	bool LocalPong(const std::string &prefix, std::deque<std::string> &params);
 
+	/** METADATA
+	 */
 	bool MetaData(const std::string &prefix, std::deque<std::string> &params);
 
+	/** VERSION
+	 */
 	bool ServerVersion(const std::string &prefix, std::deque<std::string> &params);
 
+	/** CHGHOST
+	 */
 	bool ChangeHost(const std::string &prefix, std::deque<std::string> &params);
 
+	/** ADDLINE
+	 */
 	bool AddLine(const std::string &prefix, std::deque<std::string> &params);
 
+	/** CHGNAME
+	 */
 	bool ChangeName(const std::string &prefix, std::deque<std::string> &params);
 
+	/** WHOIS
+	 */
 	bool Whois(const std::string &prefix, std::deque<std::string> &params);
 
+	/** PUSH
+	 */
 	bool Push(const std::string &prefix, std::deque<std::string> &params);
 
+	/** SETTIME
+	 */
 	bool HandleSetTime(const std::string &prefix, std::deque<std::string> &params);
 
+	/** TIME
+	 */
 	bool Time(const std::string &prefix, std::deque<std::string> &params);
 
+	/** PING
+	 */
 	bool LocalPing(const std::string &prefix, std::deque<std::string> &params);
 
+	/** Remove all modes from a channel, including statusmodes (+qaovh etc), simplemodes, parameter modes.
+	 * This does not update the timestamp of the target channel, this must be done seperately.
+	 */
 	bool RemoveStatus(const std::string &prefix, std::deque<std::string> &params);
 
+	/** <- (remote) <- SERVER
+	 */
 	bool RemoteServer(const std::string &prefix, std::deque<std::string> &params);
 
+	/** (local) -> SERVER
+	 */
 	bool Outbound_Reply_Server(std::deque<std::string> &params);
 
+	/** (local) <- SERVER
+	 */
 	bool Inbound_Server(std::deque<std::string> &params);
 
+	/** Handle netsplit
+	 */
 	void Split(const std::string &line, std::deque<std::string> &n);
 
+	/** Process complete line from buffer
+	 */
 	bool ProcessLine(std::string &line);
 
+	/** Get this server's name
+	 */
 	virtual std::string GetName();
 
+	/** Handle socket timeout from connect()
+	 */
 	virtual void OnTimeout();
 
+	/** Handle socket close event
+	 */
 	virtual void OnClose();
 
+	/** Handle incoming connection event
+	 */
 	virtual int OnIncomingConnection(int newsock, char* ip);
 };
 
 #endif
+
diff --git a/src/modules/m_spanningtree/utils.h b/src/modules/m_spanningtree/utils.h
index 734d88d5d..97c617e0a 100644
--- a/src/modules/m_spanningtree/utils.h
+++ b/src/modules/m_spanningtree/utils.h
@@ -71,7 +71,12 @@ class SpanningTreeUtilities
 	 */
 	int lines_to_apply;
 
+	/** List of module pointers which can provide I/O abstraction
+	 */
 	hookmodules hooks;
+
+	/** List of module names which can provide I/O abstraction
+	 */
 	std::vector<std::string> hooknames;
 
 	/** Initialise utility class