Fix various documentation comments.

10 files changed, 17 insertions, 24 deletions

diff --git a/include/channels.h b/include/channels.h
index 1b44a7be6..0b38958cc 100644
--- a/include/channels.h
+++ b/include/channels.h
@@ -165,7 +165,6 @@ class CoreExport Channel : public Extensible
 
 	/** Delete a user pointer to the internal reference list
 	 * @param user The user to delete
-	 * @return number of users left on the channel after deletion of the user
 	 */
 	void DelUser(User* user);
 
diff --git a/include/inspircd.h b/include/inspircd.h
index a55d52c0b..b0e9903f2 100644
--- a/include/inspircd.h
+++ b/include/inspircd.h
@@ -538,7 +538,6 @@ class CoreExport InspIRCd
 	/** Attempt to write the process id to a given file
 	 * @param filename The PID file to attempt to write to
 	 * @param exitonfail If true and the PID fail cannot be written log to stdout and exit, otherwise only log on failure
-	 * @return This function may bail if the file cannot be written
 	 */
 	void WritePID(const std::string& filename, bool exitonfail = true);
 
diff --git a/include/mode.h b/include/mode.h
index 17f7e0133..82dd75770 100644
--- a/include/mode.h
+++ b/include/mode.h
@@ -681,7 +681,7 @@ class CoreExport ModeParser : public fakederef<ModeParser>
 	 *
 	 * host.name -> *!*\@host.name
 	 *
-	 * ident@host.name -> *!ident\@host.name
+	 * ident\@host.name -> *!ident\@host.name
 	 *
 	 * This method can be used on both IPV4 and IPV6 user masks.
 	 */
diff --git a/include/modules/away.h b/include/modules/away.h
index e70b598cf..563b599fe 100644
--- a/include/modules/away.h
+++ b/include/modules/away.h
@@ -51,7 +51,6 @@ class Away::EventListener
 
 	/** Called when a user wishes to mark themselves as back.
 	 * @param user The user who is going away.
-	 * @param message The away message that the user set.
 	 * @return Either MOD_RES_ALLOW to allow the user to mark themself as back, MOD_RES_DENY to
 	 *         disallow the user to mark themself as back, or MOD_RES_PASSTHRU to let another module
 	 *         handle the event.
diff --git a/include/modules/dns.h b/include/modules/dns.h
index 141951fd3..5b1c426cd 100644
--- a/include/modules/dns.h
+++ b/include/modules/dns.h
@@ -182,12 +182,12 @@ namespace DNS
 		}
 
 		/** Called when this request succeeds
-		 * @param r The query sent back from the nameserver
+		 * @param req The query sent back from the nameserver
 		 */
 		virtual void OnLookupComplete(const Query* req) = 0;
 
 		/** Called when this request fails or times out.
-		 * @param r The query sent back from the nameserver, check the error code.
+		 * @param req The query sent back from the nameserver, check the error code.
 		 */
 		virtual void OnError(const Query* req) { }
 
diff --git a/include/modules/httpd.h b/include/modules/httpd.h
index dca35f099..ccb71595c 100644
--- a/include/modules/httpd.h
+++ b/include/modules/httpd.h
@@ -186,17 +186,18 @@ class HTTPRequest
 	/** Initialize HTTPRequest.
 	 * This constructor is called by m_httpd.so to initialize the class.
 	 * @param request_type The request type, e.g. GET, POST, HEAD
+	 * @param parsed_uri The URI which was requested by the client.
 	 * @param hdr The headers sent with the request
-	 * @param opaque An opaque pointer used internally by m_httpd, which you must pass back to the module in your reply.
+	 * @param socket The server socket which this request came in via.
 	 * @param ip The IP address making the web request.
 	 * @param pdata The post data (content after headers) received with the request, up to Content-Length in size
 	 */
-	HTTPRequest(const std::string& request_type, const HTTPRequestURI& Parseduri,
-		HTTPHeaders* hdr, HttpServerSocket* socket, const std::string &ip, const std::string &pdata)
+	HTTPRequest(const std::string& request_type, const HTTPRequestURI& parsed_uri, HTTPHeaders* hdr,
+			HttpServerSocket* socket, const std::string& ip, const std::string& pdata)
 		: type(request_type)
 		, ipaddr(ip)
 		, postdata(pdata)
-		, parseduri(Parseduri)
+		, parseduri(parsed_uri)
 		, headers(hdr)
 		, sock(socket)
 	{
diff --git a/include/modules/sql.h b/include/modules/sql.h
index 47da6f6bf..292322cda 100644
--- a/include/modules/sql.h
+++ b/include/modules/sql.h
@@ -129,9 +129,9 @@ class SQL::Result : public classbase
 	/**
 	 * Check if there's a column with the specified name in the result
 	 *
-	 * @param the column name
-	 * @param on success, this is the column index
-	 * @returns true, or false if the column is not found
+	 * @param column The column name.
+	 * @param index The place to store the column index if it exists.
+	 * @returns If the column exists then true; otherwise, false.
 	 */
 	virtual bool HasColumn(const std::string& column, size_t& index) = 0;
 };
diff --git a/include/socketengine.h b/include/socketengine.h
index 26d31c168..d8d5e406d 100644
--- a/include/socketengine.h
+++ b/include/socketengine.h
@@ -326,8 +326,6 @@ public:
 	 * failure (for example, you try and enable
 	 * epoll on a 2.4 linux kernel) then this
 	 * function may bail back to the shell.
-	 * @return void, but it is acceptable for this function to bail back to
-	 * the shell or operating system on fatal error.
 	 */
 	static void Init();
 
@@ -556,8 +554,6 @@ public:
 	 * allows for the socket engine to re-create its handle
 	 * after the daemon forks as the socket engine is created
 	 * long BEFORE the daemon forks.
-	 * @return void, but it is acceptable for this function to bail back to
-	 * the shell or operating system on fatal error.
 	 */
 	static void RecoverFromFork();
 
diff --git a/include/stdalgo.h b/include/stdalgo.h
index c0baa9dd8..585114fce 100644
--- a/include/stdalgo.h
+++ b/include/stdalgo.h
@@ -28,10 +28,10 @@ namespace stdalgo
 		 * Erase a single element from a vector by overwriting it with a copy of the last element,
 		 * which is then removed. This, in contrast to vector::erase(), does not result in all
 		 * elements after the erased element being moved.
+		 * Returns nothing, but all iterators, references and pointers to the erased element and the
+		 * last element are invalidated
 		 * @param vect Vector to remove the element from
 		 * @param it Iterator to the element to remove
-		 * @return Nothing, but all iterators, references and pointers to the erased element and the
-		 * last element are invalidated
 		 */
 		template <typename T>
 		inline void swaperase(typename std::vector<T>& vect, const typename std::vector<T>::iterator& it)
diff --git a/include/users.h b/include/users.h
index 136874bab..8045d5705 100644
--- a/include/users.h
+++ b/include/users.h
@@ -243,19 +243,19 @@ struct CoreExport ConnectClass : public refcountbase
 class CoreExport User : public Extensible
 {
  private:
-	/** Cached nick!ident@dhost value using the displayed hostname
+	/** Cached nick!ident\@dhost value using the displayed hostname
 	 */
 	std::string cached_fullhost;
 
-	/** Cached ident@ip value using the real IP address
+	/** Cached ident\@ip value using the real IP address
 	 */
 	std::string cached_hostip;
 
-	/** Cached ident@realhost value using the real hostname
+	/** Cached ident\@realhost value using the real hostname
 	 */
 	std::string cached_makehost;
 
-	/** Cached nick!ident@realhost value using the real hostname
+	/** Cached nick!ident\@realhost value using the real hostname
 	 */
 	std::string cached_fullrealhost;
 
@@ -850,7 +850,6 @@ class CoreExport LocalUser : public User, public insp::intrusive_list_node<Local
 
 	/** Set the connect class to which this user belongs to.
 	 * @param explicit_name Set this string to tie the user to a specific class name. Otherwise, the class is fitted by checking \<connect> tags from the configuration file.
-	 * @return A reference to this user's current connect class.
 	 */
 	void SetClass(const std::string &explicit_name = "");