Tons of comments

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

1 files changed, 137 insertions, 9 deletions

diff --git a/include/users.h b/include/users.h
index a01b0f28b..30111870d 100644
--- a/include/users.h
+++ b/include/users.h
@@ -164,9 +164,18 @@ class userrec : public connection
 	/** Resolvers for looking up this users hostname
 	 */
 	UserResolver* res_forward;
+
+	/** Resolvers for looking up this users hostname
+	 */
 	UserResolver* res_reverse;
+
+	/** Stored reverse lookup from res_forward
+	 */
 	std::string stored_host;
 
+	/** Starts a DNS lookup of the user's IP.
+	 * When complete, sets userrec::dns_done to true.
+	 */
 	void StartDNSLookup();
 	
 	/** The users nickname.
@@ -205,6 +214,8 @@ class userrec : public connection
 	 */
 	char snomasks[64];
 
+	/** Channels this user is on, and the permissions they have there
+	 */
 	UserChanList chans;
 	
 	/** The server the user is connected to.
@@ -271,22 +282,30 @@ class userrec : public connection
 	sockaddr* ip;
 
 	/** Initialize the clients sockaddr
+	 * @param protocol_family The protocol family of the IP address, AF_INET or AF_INET6
+	 * @param ip A human-readable IP address for this user matching the protcol_family
+	 * @param port The port number of this user or zero for a remote user
 	 */
 	void SetSockAddr(int protocol_family, const char* ip, int port);
 
 	/** Get port number from sockaddr
+	 * @return The port number of this user.
 	 */
 	int GetPort();
 
 	/** Get protocol family from sockaddr
+	 * @return The protocol family of this user, either AF_INET or AF_INET6
 	 */
 	int GetProtocolFamily();
 
 	/** Get IP string from sockaddr, using static internal buffer
+	 * @return The IP string
 	 */
 	const char* GetIPString();
 
 	/** Get IP string from sockaddr, using caller-specified buffer
+	 * @param buf A buffer to use
+	 * @return The IP string
 	 */
 	const char* GetIPString(char* buf);
 
@@ -303,12 +322,14 @@ class userrec : public connection
 	long recvqmax;
 
 	/** Default constructor
+	 * @throw Nothing at present
 	 */
 	userrec();
 	
 	/** Returns the full displayed host of the user
 	 * This member function returns the hostname of the user as seen by other users
 	 * on the server, in nick!ident&at;host form.
+	 * @return The full masked host of the user
 	 */
 	virtual char* GetFullHost();
 	
@@ -316,64 +337,97 @@ class userrec : public connection
 	 * This member function returns the hostname of the user as seen by other users
 	 * on the server, in nick!ident&at;host form. If any form of hostname cloaking is in operation,
 	 * e.g. through a module, then this method will ignore it and return the true hostname.
+	 * @return The full real host of the user
 	 */
 	virtual char* GetFullRealHost();
 
-	/*
-	 * Create a displayable mode string for this users umodes
+	/** Create a displayable mode string for this users snomasks
+	 * @return The notice mask character sequence
 	 */
 	const char* FormatNoticeMasks();
 
+	/** Process a snomask modifier string, e.g. +abc-de
+	 * @param sm A sequence of notice mask characters
+	 * @return True if the notice masks were successfully applied
+	 */
 	bool userrec::ProcessNoticeMasks(const char *sm);
 
+	/** Returns true if a notice mask is set
+	 * @param sm A notice mask character to check
+	 * @return True if the notice mask is set
+	 */
 	bool IsNoticeMaskSet(unsigned char sm);
 
+	/** Changed a specific notice mask value
+	 * @param sm The server notice mask to change
+	 * @param value An on/off value for this mask
+	 */
 	void SetNoticeMask(unsigned char sm, bool value);
 
-	/*
-	 * Create a displayable mode string for this users umodes
+	/** Create a displayable mode string for this users umodes
+	 * @param The mode string
 	 */
 	const char* FormatModes();
 
+	/** Returns true if a specific mode is set
+	 * @param m The user mode
+	 * @return True if the mode is set
+	 */
 	bool IsModeSet(unsigned char m);
 
+	/** Set a specific usermode to on or off
+	 * @param m The user mode
+	 * @param value On or off setting of the mode
+	 */
 	void SetMode(unsigned char m, bool value);
 	
 	/** Returns true if a user is invited to a channel.
+	 * @param channel A channel name to look up
+	 * @return True if the user is invited to the given channel
 	 */
 	virtual bool IsInvited(irc::string &channel);
 	
 	/** Adds a channel to a users invite list (invites them to a channel)
+	 * @param channel A channel name to add
 	 */
 	virtual void InviteTo(irc::string &channel);
 	
 	/** Removes a channel from a users invite list.
 	 * This member function is called on successfully joining an invite only channel
 	 * to which the user has previously been invited, to clear the invitation.
+	 * @param channel The channel to remove the invite to
 	 */
 	virtual void RemoveInvite(irc::string &channel);
 	
 	/** Returns true or false for if a user can execute a privilaged oper command.
 	 * This is done by looking up their oper type from userrec::oper, then referencing
 	 * this to their oper classes and checking the commands they can execute.
+	 * @param command A command (should be all CAPS)
+	 * @return True if this user can execute the command
 	 */
 	bool HasPermission(const std::string &command);
 
 	/** Calls read() to read some data for this user using their fd.
+	 * @param buffer The buffer to read into
+	 * @param size The size of data to read
+	 * @return The number of bytes read, or -1 if an error occured.
 	 */
 	int ReadData(void* buffer, size_t size);
 
-	/** This method adds data to the buffer of the user.
+	/** This method adds data to the read buffer of the user.
 	 * The buffer can grow to any size within limits of the available memory,
 	 * managed by the size of a std::string, however if any individual line in
 	 * the buffer grows over 600 bytes in length (which is 88 chars over the
 	 * RFC-specified limit per line) then the method will return false and the
 	 * text will not be inserted.
+	 * @param a The string to add to the users read buffer
+	 * @return True if the string was successfully added to the read buffer
 	 */
 	bool AddBuffer(const std::string &a);
 
 	/** This method returns true if the buffer contains at least one carriage return
 	 * character (e.g. one complete line may be read)
+	 * @return True if there is at least one complete line in the users buffer
 	 */
 	bool BufferIsReady();
 
@@ -387,6 +441,7 @@ class userrec : public connection
 	 * multiple lines if they are available. The results of this function if there
 	 * are no lines to be read are unknown, always use BufferIsReady() to check if
 	 * it is ok to read the buffer before calling GetBuffer().
+	 * @return The string at the tail end of this users buffer
 	 */
 	std::string GetBuffer();
 
@@ -394,11 +449,13 @@ class userrec : public connection
 	 * of a client may occur at an inopportune time such as half way through /LIST output.
 	 * The WriteErrors of clients are checked at a more ideal time (in the mainloop) and
 	 * errored clients purged.
+	 * @param error The error string to set.
 	 */
 	void SetWriteError(const std::string &error);
 
 	/** Returns the write error which last occured on this connection or an empty string
 	 * if none occured.
+	 * @return The error string which has occured for this user
 	 */
 	const char* GetWriteError();
 
@@ -406,6 +463,7 @@ class userrec : public connection
 	 * You may add any amount of text up to this users sendq value, if you exceed the
 	 * sendq value, SetWriteError() will be called to set the users error string to
 	 * "SendQ exceeded", and further buffer adds will be dropped.
+	 * @param data The data to add to the write buffer
 	 */
 	void AddWriteBuf(const std::string &data);
 
@@ -418,16 +476,19 @@ class userrec : public connection
 	void FlushWriteBuf();
 
 	/** Returns the list of channels this user has been invited to but has not yet joined.
+	 * @return A list of channels the user is invited to
 	 */
 	InvitedList* GetInviteList();
 
 	/** Creates a wildcard host.
 	 * Takes a buffer to use and fills the given buffer with the host in the format *!*@hostname
+	 * @return The wildcarded hostname in *!*@host form
 	 */
 	char* MakeWildHost();
 
 	/** Creates a host.
 	 * Takes a buffer to use and fills the given buffer with the host in the format nick!user@host
+	 * @param Buffer to fill with host information
 	 */
 	void MakeHost(char* nhost);
 
@@ -436,22 +497,64 @@ class userrec : public connection
 	void CloseSocket();
 
 	/** Disconnect a user gracefully
+	 * @param user The user to remove
+	 * @param r The quit reason
 	 */
 	static void QuitUser(userrec *user, const std::string &r);
 
+	/** Add the user to WHOWAS system
+	 */
 	void AddToWhoWas();
 
+	/** Oper up the user using the given opertype.
+	 * This will also give the +o usermode.
+	 * @param opertype The oper type to oper as
+	 */
 	void Oper(const std::string &opertype);
 
+	/** Use this method to fully connect a user.
+	 * This will send the message of the day, check G/K/E lines, etc.
+	 * @param Goners If the user is disconnected by this method call, the
+	 * value of 'this' will be pushed onto this CullList. This is used by
+	 * the core to connect many users in rapid succession without invalidating
+	 * iterators.
+	 */
 	void FullConnect(CullList* Goners);
+
+	/** Change this users hash key to a new string.
+	 * You should not call this function directly. It is used by the core
+	 * to update the users hash entry on a nickchange.
+	 * @param New new user_hash key
+	 * @return Pointer to userrec in hash (usually 'this')
+	 */
 	userrec* UpdateNickHash(const char* New);
+
+	/** Force a nickname change.
+	 * If the nickname change fails (for example, because the nick in question
+	 * already exists) this function will return false, and you must then either
+	 * output an error message, or quit the user for nickname collision.
+	 * @param newnick The nickname to change to
+	 * @return True if the nickchange was successful.
+	 */
 	bool ForceNickChange(const char* newnick);
 
+	/** Add a client to the system.
+	 * This will create a new userrec, insert it into the user_hash,
+	 * initialize it as not yet registered, and add it to the socket engine.
+	 */
 	static void AddClient(int socket, int port, bool iscached, insp_inaddr ip);
 
+	/** Oper down.
+	 * This will clear the +o usermode and unset the user's oper type
+	 */
 	void UnOper();
 
+	/** Return the number of global clones of this user
+	 */
 	long GlobalCloneCount();
+
+	/** Return the number of local clones of this user
+	 */
 	long LocalCloneCount();
 
 	/** Default destructor
@@ -459,31 +562,56 @@ class userrec : public connection
 	virtual ~userrec();
 };
 
-/** Used to hold WHOWAS information
- */
 
 namespace irc
 {
+	/** Holds whowas related functions and classes
+	 */
 	namespace whowas
 	{
 
+		/** Used to hold WHOWAS information
+		 */
 		class WhoWasGroup : public classbase
 		{
 		 public:
+			/** Real host
+			 */
 			char* host;
+			/** Displayed host
+			 */
 			char* dhost;
+			/** Ident
+			 */
 			char* ident;
+			/** Server name
+			 */
 			const char* server;
+			/** Fullname (GECOS)
+			 */
 			char* gecos;
+			/** Signon time
+			 */
 			time_t signon;
 	
+			/** Initialize this WhoQasFroup with a user
+			 */
 			WhoWasGroup(userrec* user);
+			/** Destructor
+			 */
 			~WhoWasGroup();
 		};
-	
+
+		/** A group of users related by nickname
+		 */
 		typedef std::deque<WhoWasGroup*> whowas_set;
+
+		/** Sets of users in the whowas system
+		 */
 		typedef std::map<irc::string,whowas_set*> whowas_users;
-	
+
+		/** Called every hour by the core to remove expired entries
+		 */
 		void MaintainWhoWas(time_t TIME);
 	};
 };