Added parameters

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

3 files changed, 70 insertions, 5 deletions

diff --git a/include/base.h b/include/base.h
index c959cf869..d253c5dc3 100644
--- a/include/base.h
+++ b/include/base.h
@@ -56,23 +56,34 @@ class Extensible : public classbase
 public:
 
 	/** Extend an Extensible class.
+	 *
+	 * @param key The key parameter is an arbitary string which identifies the extension data
+	 * @param p This parameter is a pointer to any data you wish to associate with the object
+	 *
 	 * You must provide a key to store the data as, and a void* to the data (typedef VoidPointer)
 	 * The data will be inserted into the map. If the data already exists, you may not insert it
 	 * twice, Extensible::Extend will return false in this case.
-	 * On successful extension, Extend returns true.
+	 *
+	 * @return Returns true on success, false if otherwise
 	 */
 	bool Extend(std::string key, char* p);
 
 	/** Shrink an Extensible class.
+	 *
+	 * @param key The key parameter is an arbitary string which identifies the extension data
+	 *
 	 * You must provide a key name. The given key name will be removed from the classes data. If
 	 * you provide a nonexistent key (case is important) then the function will return false.
-	 * Returns true on success.
+	 *
+	 * @return Returns true on success.
 	 */
 	bool Shrink(std::string key);
 	
 	/** Get an extension item.
-	 * You must provide a key name, which is case sensitive. If you provide a non-existent key name,
-	 * the function returns NULL, otherwise a pointer to the item referenced by the key is returned.
+	 *
+	 * @param key The key parameter is an arbitary string which identifies the extension data
+	 *
+	 * @return If you provide a non-existent key name, the function returns NULL, otherwise a pointer to the item referenced by the key is returned.
 	 */
 	char* GetExt(std::string key);
 };
diff --git a/include/channels.h b/include/channels.h
index 7df2d665e..ed57955a2 100644
--- a/include/channels.h
+++ b/include/channels.h
@@ -149,22 +149,33 @@ class chanrec : public Extensible
 	BanList bans;
 	
 	/** Sets or unsets a custom mode in the channels info
+	 * @param mode The mode character to set or unset
+	 * @param mode_on True if you want to set the mode or false if you want to remove it
 	 */
 	void SetCustomMode(char mode,bool mode_on);
 
 	/** Sets or unsets the parameters for a custom mode in a channels info
+	 * @param mode The mode character to set or unset
+	 * @param parameter The parameter string to associate with this mode character
+	 * @param mode_on True if you want to set the mode or false if you want to remove it
 	 */
 	void SetCustomModeParam(char mode,char* parameter,bool mode_on);
  
 	/** Returns true if a custom mode is set on a channel
+	  * @param mode The mode character you wish to query
+	  * @return True if the custom mode is set, false if otherwise
 	  */
 	bool IsCustomModeSet(char mode);
 
 	/** Returns the parameter for a custom mode on a channel.
+	  * @param mode The mode character you wish to query
+	  *
 	  * For example if "+L #foo" is set, and you pass this method
 	  * 'L', it will return '#foo'. If the mode is not set on the
 	  * channel, or the mode has no parameters associated with it,
 	  * it will return an empty string.
+	  *
+	  * @return The parameter for this mode is returned, or an empty string
 	  */
 	std::string GetModeParameter(char mode);
 
@@ -172,10 +183,14 @@ class chanrec : public Extensible
 	 * This returns the channel reference counter, which is initialized
 	 * to 0 when the channel is created and incremented/decremented
 	 * upon joins, parts quits and kicks.
+	 *
+	 * @return The number of users on this channel
 	 */
 	long GetUserCounter();
 
 	/** Add a user pointer to the internal reference list
+	 * @param castuser This should be a pointer to a userrec, casted to char*
+	 *
 	 * The data inserted into the reference list is a table as it is
 	 * an arbitary pointer compared to other users by its memory address,
 	 * as this is a very fast 32 or 64 bit integer comparison.
@@ -183,6 +198,8 @@ class chanrec : public Extensible
 	void AddUser(char* castuser);
 
         /** Delete a user pointer to the internal reference list
+	 * @param castuser This should be a pointer to a userrec, casted to char*
+	 *
          * The data removed from the reference list is a table as it is
          * an arbitary pointer compared to other users by its memory address,
          * as this is a very fast 32 or 64 bit integer comparison.
@@ -195,6 +212,8 @@ class chanrec : public Extensible
 	 * channel membership for PRIVMSG, NOTICE, QUIT, PART etc.
 	 * The resulting pointer to the vector should be considered
 	 * readonly and only modified via AddUser and DelUser.
+	 *
+	 * @return This function returns a vector of userrec pointers, each of which has been casted to char* to prevent circular references
 	 */
 	std::vector<char*> *GetUsers();
 
diff --git a/include/connection.h b/include/connection.h
index 88dc3ea54..2d473bde4 100644
--- a/include/connection.h
+++ b/include/connection.h
@@ -141,34 +141,42 @@ class ircd_connector : public Extensible
 	std::string GetServerName();
 	
 	/** Set the server name of this connection
+	 * @param serv The server name to set
 	 */
 	void SetServerName(std::string serv);
 	
 	/** Get the file descriptor associated with this connection
+	 * @return The file descriptor associated with this connection
 	 */
 	int GetDescriptor();
 	
 	/** Set the file descriptor for this connection
+	 * @param fd The file descriptor to associate with the connection
 	 */
 	void SetDescriptor(int fd);
 	
 	/** Get the state flags for this connection
+	 * @return The state flags associated with this connection
 	 */
 	int GetState();
 	
 	/** Set the state flags for this connection
+	 * @param state The state flags to set for this connection
 	 */
 	void SetState(int state);
 	
 	/** Get the ip address (not servername) associated with this connection
+	 * @return The connections IP address in dotted decimal form
 	 */
 	char* GetServerIP();
 	
 	/** Get the server description of this connection
+	 * @return The description (GECOS) of this connection
 	 */
 	std::string GetDescription();
 	
 	/** Set the server description of this connection
+	 * @param desc The description (GECOS) of this connection to be set
 	 */
 	void SetDescription(std::string desc);
 	
@@ -176,14 +184,20 @@ class ircd_connector : public Extensible
 	 * If the connection is outbound this will be the remote port
 	 * otherwise it will be the local port, so it can always be
 	 * gautanteed as open at the address given in GetServerIP().
+	 *
+	 * @return The port number of this connection
 	 */
 	int GetServerPort();
 	
 	/** Set the port used by this connection
+	 * @param p The port number to set for this connection
 	 */
 	void SetServerPort(int p);
 	
 	/** Set both the host and the port in one operation for this connection
+	 * @param newhost The hostname to set for this connection
+	 * @param newport The port number to set for this connection
+	 * @return True on success, false on failure
 	 */
 	bool SetHostAndPort(char* newhost, int newport);
 	
@@ -193,14 +207,20 @@ class ircd_connector : public Extensible
 	void CloseConnection();
 
 	/** This method adds text to the ircd connection's buffer
+	 * @param a The text to add to the buffer up to a maximum size of 1MB
+	 *
 	 * This buffer's maximum size is one megabyte, the method returning false
 	 * if the buffer is full.
+	 *
+	 * @return True on success, false if the buffer is full or the connection is down
 	 */
 	bool AddBuffer(std::string a);
 
 	/** This method returns true if the buffer contains at least one
 	 * carriage return character, e.g. one line can be read from the
 	 * buffer successfully.
+	 *
+	 * @return True if there is at least one complete line waiting to be processed
 	 */
 	bool BufferIsComplete();
 
@@ -211,42 +231,57 @@ class ircd_connector : public Extensible
 	/** This method retrieves the first string from the tail end of the
 	 * buffer and advances the tail end of the buffer past the returned
 	 * string, in a similar manner to strtok().
+	 *
+	 * @return The first line of the buffer up to a carriage return
 	 */
 	std::string GetBuffer();
 
 	/** This method sets the version string of the remote server
+	 * @param newversion The version string to set
 	 */
         void SetVersionString(std::string newversion);
 
 	/** This method returns the version string of the remote server.
 	 * If the server has no version string an empty string is returned.
+	 *
+	 * @return The version text of this connection
 	 */
         std::string GetVersionString();
 
-	/** Adds data to the connection's sendQ to be flushed later
+	/** Adds data to the connection's sendQ to be flushed later.
+	 * @param data The data to add to the write buffer
+	 *
 	 * Fails if there is an error pending on the connection.
+	 *
+	 * @return True on success, false if the connection is down or the buffer is full
 	 */
 	bool AddWriteBuf(std::string data);
 
 	/** Flushes as much of the data from the buffer as possible,
 	 * and advances the queue pointer to what is left.
+	 *
+	 * @return True if the flush succeeded, false if the connection is down
 	 */
 	bool FlushWriteBuf();
 
 	/** Sets the error string for this connection
+	 * @param error The error string to set
 	 */
 	void SetWriteError(std::string error);
 
 	/** Gets the error string for this connection
+	 * @return The last error to occur or an empty string
 	 */
 	std::string GetWriteError();
 
 	/** Returns true if there is data to be written that hasn't been sent yet
+	 * @return True if the buffer is not empty
 	 */
 	bool HasBufferedOutput();
 
 	/** Checks if the connection replied to its last ping, and if it did
 	 * sends another and returns true, if not, returns false.
+	 * @return True if the server is still replying to pings
 	 */
 	bool CheckPing();