3 files changed, 53 insertions, 8 deletions

diff --git a/include/connection.h b/include/connection.h
index e8af1b648..300a83d4a 100644
--- a/include/connection.h
+++ b/include/connection.h
@@ -79,6 +79,8 @@ class ircd_connector : public Extensible
 	 */
 	bool SetHostAddress(char* host, int port);
 
+	/** This string holds the ircd's version response
+	 */
 	std::string version;
 
  public:
@@ -169,12 +171,36 @@ class ircd_connector : public Extensible
 	 */
 	void CloseConnection();
 
+	/** This method adds text to the ircd connection's buffer
+	 * There is no limitation on how much text of what line width may
+	 * be added to this buffer. It is the sending server's responsibility
+	 * to ensure sent data is kept within reasonable quanities.
+	 */
 	void 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.
+	 */
 	bool BufferIsComplete();
+
+	/** This method clears the server's buffer by setting it to an empty string.
+	 */
 	void ClearBuffer();
+
+	/** 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().
+	 */
 	std::string GetBuffer();
 
+	/** This method sets the version string of the remote server
+	 */
         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.
+	 */
         std::string GetVersionString();
 };
 
@@ -303,10 +329,6 @@ class connection : public Extensible
 	 */
 	bool AddIncoming(int fd,char* targethost, int sourceport);
 	
-	/** This function is deprecated and may be removed in a later alpha/beta
-	 */
-	long GenKey();
-
 };
 
 
diff --git a/include/inspircd.h b/include/inspircd.h
index d5f149456..f0199e9dc 100644
--- a/include/inspircd.h
+++ b/include/inspircd.h
@@ -162,6 +162,7 @@ bool LoadModule(const char* filename);
 bool UnloadModule(const char* filename);
 char* ModuleError();
 void NoticeAll(userrec *source, bool local_only, char* text, ...);
+void NoticeAllOpers(userrec *source, bool local_only, char* text, ...);
 
 // mesh network functions
 
diff --git a/include/users.h b/include/users.h
index 0dfbc2223..73e1a1173 100644
--- a/include/users.h
+++ b/include/users.h
@@ -227,10 +227,32 @@ class userrec : public connection
 	 */
 	bool HasPermission(char* command);
 
-	bool userrec::AddBuffer(std::string a);
-	bool userrec::BufferIsReady();
-	void userrec::ClearBuffer();
-	std::string userrec::GetBuffer();
+	/** This method adds data to the 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.
+	 */
+	bool AddBuffer(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)
+	 */
+	bool BufferIsReady();
+
+	/** This function clears the entire buffer by setting it to an empty string.
+	 */
+	void ClearBuffer();
+
+	/** This method returns the first available string at the tail end of the buffer
+	 * and advances the tail end of the buffer past the string. This means it is
+	 * a one way operation in a similar way to strtok(), and multiple calls return
+	 * 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().
+	 */
+	std::string GetBuffer();
 	
 };