Finished adding JSDoc for src/utils

src/utils/loggerUtils.js

@@ -17,6 +17,15 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>.*/
 //Config
 const config = require('../../config.json');
 
+/**
+ * Creates and returns a custom exception, tagged as a 'custom' exception, using the 'custom' boolean property.
+ * This is used to denote that this error was generated on purpose, with a human readable message, that can be securely sent to the client.
+ * Unexpected exceptions should only be logged internally, however, as they may contain sensitive data.
+ * 
+ * @param {String} msg - Error message to send the client
+ * @param {String} type - Error type to send back to the client
+ * @returns {Error} The exception to smith
+ */
 module.exports.exceptionSmith = function(msg, type){
         //Create the new error with the given message
         const exception = new Error(msg);
@@ -31,6 +40,14 @@ module.exports.exceptionSmith = function(msg, type){
         return exception;
 }
 
+/**
+ * Main error handling function
+ * @param {Express.Response} res - Response being sent out to the client who caused the issue
+ * @param {String} msg - Error message to send the client
+ * @param {String} type - Error type to send back to the client
+ * @param {Number} status - HTTP(s) Status Code to send back to the client
+ * @returns {Express.Response} If we have a usable Express Response object, return it back after it's been cashed
+ */
 module.exports.errorHandler = function(res, msg, type = "Generic", status = 400){
         //Some controllers do things after sending headers, for those, we should remain silent
         if(!res.headersSent){
@@ -39,6 +56,10 @@ module.exports.errorHandler = function(res, msg, type = "Generic", status = 400)
         }
 }
 
+/**
+ * Handles local exceptions which where not directly created by user interaction
+ * @param {Error} err - Exception to handle
+ */
 module.exports.localExceptionHandler = function(err){
         //If we're being verbose
         if(config.verbose){
@@ -47,6 +68,11 @@ module.exports.localExceptionHandler = function(err){
         }
 }
 
+/**
+ * Handles exceptions which where directly the fault of user action >:(
+ * @param {Express.Response} res - Express Response object to bitch at
+ * @param {Error} err - Error created by the jerk in question
+ */
 module.exports.exceptionHandler = function(res, err){
         //If this is a self-made problem
         if(err.custom){
@@ -60,14 +86,27 @@ module.exports.exceptionHandler = function(res, err){
         }
 }
 
+/**
+ * Basic error-handling for socket.io so we don't just silently swallow errors.
+ * @param {Socket} socket - Socket error originated from
+ * @param {String} msg - Error message to send the client
+ * @param {String} type - Error type to send back to the client
+ * @returns {Boolean} - Passthrough from socket.emit
+ */
 module.exports.socketErrorHandler = function(socket, msg, type = "Generic"){
         return socket.emit("error", {errors: [{type, msg, date: new Date()}]});
 }
 
+/**
+ * Generates error messages for simple errors generated by socket.io interaction
+ * @param {Socket} socket - Socket error originated from
+ * @param {Error} err - Error created by the jerk in question
+ * @returns {Boolean} - Passthrough from socket.emit
+ */
 module.exports.socketExceptionHandler = function(socket, err){
         //If this is a self made problem
         if(err.custom){
-                //at the browser for fucking up, and tell it what it did wrong.
+                //yell at the browser for fucking up, and tell it what it did wrong.
                 return module.exports.socketErrorHandler(socket, err.message, err.type);
         }else{
                 //Locally handle the exception
@@ -78,6 +117,12 @@ module.exports.socketExceptionHandler = function(socket, err){
         }
 }
 
+/**
+ * Generates error messages and drops connection for critical errors caused by socket.io interaction
+ * @param {Socket} socket - Socket error originated from
+ * @param {Error} err - Error created by the jerk in question
+ * @returns {Boolean} - Passthrough from socket.disconnect
+ */
 module.exports.socketCriticalExceptionHandler = function(socket, err){
         //If this is a self made problem
         if(err.custom){
@@ -93,11 +138,21 @@ module.exports.socketCriticalExceptionHandler = function(socket, err){
         return socket.disconnect();
 }
 
+/**
+ * Prints warning text to server console
+ * @param {String} string - String to print to console
+ */
 module.exports.consoleWarn = function(string){
         console.warn('\x1b[31m\x1b[4m%s\x1b[0m',string);
 }
 
-//Basic error-handling middleware to ensure we're not dumping stack traces
+/**
+ * Basic error-handling middleware to ensure we're not dumping stack traces to the client, as that would be insecure
+ * @param {Error} err - Error to handle
+ * @param {Express.Request} req - Express Request
+ * @param {Express.Response} res - Express Response
+ * @param {Function} next - Next function in the Express middleware chain (Not that it's getting called XP)
+ */
 module.exports.errorMiddleware = function(err, req, res, next){
         //Set generic error
         var reason = "Server Error";