Lotsa comments

scripts/Snitch/Snitch.gml

@@ -1,9 +1,9 @@
 /// Concatenates a series of values into a single string and outputs them to the IDE's Output window
+/// You can (and maybe should?) rename this function to whatever you want e.g. log()
 /// 
 /// If logging is turned on (see SnitchLogSet()) then the string is also saved to a log file on disk (in game_save_id)
 ///   N.B. This can cause slowdown if a lot of debug messages are being saved!
 /// 
-/// You can (and maybe should?) rename this function to whatever you want e.g. log()
 /// 
 /// @param value
 /// @param [value]...

scripts/SnitchAsyncHTTPEvent/SnitchAsyncHTTPEvent.gml

@@ -8,6 +8,7 @@ function SnitchAsyncHTTPEvent()
     var _id = string(async_load[? "id"]);
     if (variable_struct_exists(global.__snitchHTTPRequests, _id))
     {
+        //Pass the response into the request's response handler
         global.__snitchHTTPRequests[$ _id].HTTPResponse(async_load[? "http_status"], async_load[? "status"]);
     }
 }

scripts/SnitchCrashDumpCollect/SnitchCrashDumpCollect.gml

@@ -1,8 +1,7 @@
-/// Checks whether a crash happened the last time that the game was run
+/// Checks whether a crash dump exists on disk and returns it if so
 /// 
-/// If so, this function returns the exception struct that was generated
-/// If the crash dump couldn't be parsed, this function will return a generic exception struct
-/// Otherwise, this function returns <undefined>
+/// If an crash dump exists, this function returns the exception struct that was generated
+/// If the crash dump couldn't be parsed or no crash dump exists, this function returns <undefined>
 
 function SnitchCrashDumpCollect()
 {

scripts/SnitchCrashDumpDelete/SnitchCrashDumpDelete.gml

@@ -1,4 +1,4 @@
-/// Deletes the last crash dump from disk
+/// Deletes the crash dump from disk, if one exists
 
 function SnitchCrashDumpDelete()
 {

scripts/SnitchCrumb/SnitchCrumb.gml

@@ -1,10 +1,63 @@
-/// Creates a new breadcrumb, adds it to Snitch's internal breadcrumb array, and returns the breadcrumb struct itself
-/// Breadcrumbs will be attached to any events to help you debug your game
+/// Concatenates a series of values into a single string, creates a breadcrumb struct, and adds it to Snitch's internal breadcrumb array
+/// This function returns 
+/// You can (and maybe should?) rename this function to whatever you want e.g. crumb()
+/// 
+/// Breadcrumbs will be attached to any events (see SnitchEvent()) to help you debug your game
 /// If SNITCH_OUTPUT_BREADCRUMBS is set to <true>, the breadcrumb will also be outputted to the console (and can also be logged to file)
 /// 
-/// You can (and maybe should?) rename this function to whatever you want e.g. crumb()
+/// Breadcrumb structs have a number of methods that can be chained together in a "fluent interface" i.e.:
+/// 
+///   SnitchCrumb("Shop has no items remaining").Debug().Category("Shop UI");
+/// 
+/// Breadcrumb methods are used to set properties for the breadcrumb, such as message level or category
+/// These are as follows:
+/// 
+/// .Info()
+///     Sets the breadcrumb level to "info". If no type has been set, this sets the type to "info"
+///     
+/// .Debug()
+///     Sets the breadcrumb level to "debug". If no type has been set, this sets the type to "debug"
+///     
+/// .Warning()
+///     Sets the breadcrumb level to "warning". If no type has been set, this sets the type to "warning"
+///     
+/// .Error()
+///     Sets the breadcrumb level to "error". If no type has been set, this sets the type to "error"
+///     
+/// .Fatal()
+///     Sets the breadcrumb level to "fatal". If no type has been set, this sets the type to "error" (not a typo)
+///     
+/// .Navigation(from, to)
+///     Sets the breadcrumb type to "navigation", and sets the start/end points to the given values
+///     If no level has been set, this sets the level to "info"
+///     
+/// .HTTP(url, method, statusCode)
+///     Sets the breadcrumb level to "http". The URL/method/statusCode arguments are recorded as well
+///     If no level has been set, this sets the level to "info"
+///     
+/// .Query()
+///     Sets the breadcrumb type to "query". If no level has been set, this sets the level to "info"
+///     
+/// .Transaction()
+///     Sets the breadcrumb type to "transaction". If no level has been set, this sets the level to "info"
+///     
+/// .UI()
+///     Sets the breadcrumb type to "ui". If no level has been set, this sets the level to "info"
+///     
+/// .User()
+///     Sets the breadcrumb type to "user". If no level has been set, this sets the level to "info"
+///     
+/// .Category(string)
+///     Sets the breadcrumb's category to the given string
+///     
+/// .AddData(key, value)
+///     Adds a key-value pair of data to the breadcrumb
+///     
+/// .Logger(string)
+///     Sets the logger name to the given string
+///     
+/// 
 /// 
-/// Breadcrumb structs have a few methods that can be used to contextualise data
 /// 
 /// @param value
 /// @param [value]...

scripts/SnitchEvent/SnitchEvent.gml

@@ -1,11 +1,75 @@
-/// Creates a new event and returns the event struct itself. The event will also be outputted to the console (and can also be logged to file)
-/// When used with sentry.io, events will be sent to the sentry.io server so that you can find problem areas to improve upon
-/// Whilkst this function is mostly intended to be used with the sentry.io integration, it can also be used offline
-/// Event structs have a few methods that can be used to contextualise data
-///   N.B. The .Finish() method must be called on each and every event struct
-/// 
+/// Concatenates a series of values into a string, and creates a new event using the string
+/// If communication with sentry.io is enabled then the event will be sent to the remote logging server
+/// Events automatically have breadcrumbs attached to them. Breadcrumbs can be created using SnitchCrumb()
 /// You can (and maybe should?) rename this function to whatever you want e.g. debugEvent()
 /// 
+/// 
+/// 
+/// This function returns an event struct. The event struct *must* have its .Finish() method called i.e.:
+///   
+///   SnitchEvent("Player found a secret level").Finish();
+///   
+/// Event structs have a number of methods that can be chained together in a "fluent interface" i.e.:
+/// 
+///   SnitchEvent("Player is outside the level?!").Debug().LogCallstack().Finish();
+/// 
+/// Event methods are used to set properties for the event, such as message level or callstack logging
+/// These are as follows:
+/// 
+/// .Info()
+///     Sets the event level to "info", the lowest event level
+///     
+/// .Debug()
+///     Sets the event level to "debug"
+///     
+/// .Warning()
+///     Sets the event level to "warning"
+///     
+/// .Error()
+///     Sets the event level to "error"
+///     
+/// .Fatal()
+///     Sets the event level to "fatal", the highest event level
+///     
+/// .Finish()
+///     Finalises the event, outputting information to the debug console if required
+///     Additionally, if sentry.io communication is enabled, .Finish() will send the HTTP request
+///     If request backups are enabled, a request backup is also saved. See SNITCH_REQUEST_BACKUP_ENABLE for more information
+///     This function typically returns <undefined>, but if an HTTP request has been sent, this function returns the request struct
+///     If .ForceRequest() has been called for the event then .Finish() will awlays return a request struct
+///     
+/// .Exception(exceptionStruct)
+///     Sets a number of attributes based on a standard GameMaker exception struct
+///     This function overwrites values set by .LongMessage() and .Callstack()
+///     Additionally, any message set when creating the event will be overwritten by the .message variable in the exception struct
+///     
+/// .LongMessage(string)
+///     Sets the event's "longMessage" property. This is used for error-level and fatal-level events to add extra context
+///     
+/// .Callstack([callstackArray], [trimCount])
+///     Sets the event's callstack. If no arguments are provided then the callstack is generated from where this function was called
+///     The optional [trimCount] argument allows for the given number of callstack levels to be removed
+///     
+/// .LogCallstack()
+///      Instructs the event to output its callstack to the console
+///      If logging is enabled, this information will also be outputted to the log file
+///     
+/// .ForceRequest()
+///      Instructs the event to always return a request struct, even if sentry.io communication is disabled
+///      
+/// .Payload(struct)
+///      Overrides the use of the shared event payload (see __SnitchSharedEventPayload()) for a custom struct
+///      The following member variables will always be automatically set by Snitch no matter what payload is used:
+///        .event_id
+///        .timestamp
+///        .level
+///        .breadcrumbs
+///        .stacktrace
+///        ."sentry.interfaces.Message"
+///        .exception
+/// 
+/// 
+/// 
 /// @param value
 /// @param [value]...
 

scripts/SnitchLogGet/SnitchLogGet.gml

@@ -1,4 +1,5 @@
-/// Gets whether Snitch is saving debug message to file
+/// Returns whether Snitch is able to log messages to disk
+/// This function will always return <false> is SNITCH_LOG_PERMITTED is set to <false>
 
 function SnitchLogGet()
 {

scripts/SnitchLogSet/SnitchLogSet.gml

@@ -1,5 +1,5 @@
 /// Sets whether Snitch should log message to a file on disk (in game_save_id)
-///
+/// 
 /// @param state
 
 function SnitchLogSet(_state)
@@ -35,7 +35,7 @@ function SnitchLogSet(_state)
                         --_i;
                     }
 
-                    //Build a string for the OS info
+                    //Output lots of data to the log
                     buffer_write(global.__snitchBuffer, buffer_text, "date = " + date_datetime_string(date_current_datetime()));
                     buffer_write(global.__snitchBuffer, buffer_u8, 10);
                     buffer_write(global.__snitchBuffer, buffer_text, "config = " + string(os_get_config()));

scripts/SnitchSentrySet/SnitchSentrySet.gml

@@ -1,7 +1,7 @@
 /// Sets whether Snitch should send data to a sentry.io endpoint
 ///   N.B. sentry.io communication cannot be enabled if SNITCH_SENTRY_PERMITTED is set to <false>
 /// Details of the sentry.io integration, including the HTTP endpoint to use, can be set in __SnitchConfig()
-///
+/// 
 /// @param state
 
 function SnitchSentrySet(_state)

scripts/SnitchStepEvent/SnitchStepEvent.gml

@@ -24,7 +24,7 @@ function SnitchStepEvent()
                         //...and if we're not waiting for a response for this particular request, resend it
                         if (asyncID < 0)
                         {
-                            __SnitchTrace("Trying to resend event ", _uuid);
+                            if (SNITCH_REQUEST_BACKUP_OUTPUT_ATTEMPT) __SnitchTrace("Trying to resend event ", _uuid);
                             __SnitchSentryHTTPRequest(self);
                             global.__snitchRequestBackupResendTime = current_time;
                         }
@@ -42,6 +42,7 @@ function SnitchStepEvent()
         }
     }
 
+    //Check for any unfinished events
     if (global.__snitchUnfinishedEvent != undefined)
     {
         if (SNITCH_UNFINISHED_EVENT_ERROR)

scripts/__SnitchConfig/__SnitchConfig.gml

@@ -143,6 +143,11 @@
 //This value is in milliseconds, so 900000 is the same as 15 minutes
 #macro  SNITCH_REQUEST_BACKUP_RESEND_FAILURE_TIMEOUT  900000
 
+//Whether to output request backup send attempts to the console
+//This is handy for confirming request backups are being processed properly
+//If logging is enabled, this information will also be outputted to the log file
+#macro  SNITCH_REQUEST_BACKUP_OUTPUT_ATTEMPT  false
+
 #endregion
 
 

scripts/__SnitchSystem/__SnitchSystem.gml

@@ -37,7 +37,17 @@ function __SnitchInit()
         global.__snitchUnfinishedEvent     = undefined;
         global.__snitchSentryEnabled       = false;
         global.__snitchBuffer              = buffer_create(SNITCH_LOG_BUFFER_START_SIZE, buffer_grow, 1);
-        global.__snitchBreadcrumbsArray           = [];
+        global.__snitchBreadcrumbsArray    = [];
+
+        //HTTP-related tracking
+        global.__snitchHTTPHeaderMap               = ds_map_create(); //Has to be a map due to GameMaker's HTTP request API
+        global.__snitchHTTPRequests                = {};
+        global.__snitchRequestBackups              = {};
+        global.__snitchRequestBackupOrder          = [];
+        global.__snitchRequestBackupManifestBuffer = buffer_create(512, buffer_grow, 1);
+        global.__snitchRequestBackupResendTime     = -SNITCH_REQUEST_BACKUP_RESEND_DELAY; //Try to send a request backup immediately on boot
+        global.__snitchRequestBackupResendIndex    = 0;
+        global.__snitchRequestBackupFailures       = 0;
 
         //Build an array for the boot parameters
         SNITCH_BOOT_PARAMETERS = [];
@@ -49,7 +59,6 @@ function __SnitchInit()
         }
 
 
-
         #region Set SNITCH_OS_NAME, SNITCH_OS_VERSION, SNITCH_DEVICE_NAME, SNITCH_BROWSER, SNITCH_OS_INFO
 
         SNITCH_OS_NAME     = "Unknown (=" + string(os_type) + ")"
@@ -198,22 +207,9 @@ function __SnitchInit()
             }
         }
 
-
-
         //Create the shared event payload
         SNITCH_SHARED_EVENT_PAYLOAD = __SnitchSharedEventPayload();
 
-
-
-        global.__snitchHTTPHeaderMap               = ds_map_create(); //Has to be a map due to GameMaker's HTTP request API
-        global.__snitchHTTPRequests                = {};
-        global.__snitchRequestBackups              = {};
-        global.__snitchRequestBackupOrder          = [];
-        global.__snitchRequestBackupManifestBuffer = buffer_create(512, buffer_grow, 1);
-        global.__snitchRequestBackupResendTime     = -SNITCH_REQUEST_BACKUP_RESEND_DELAY; //Try to send a request backup immediately on boot
-        global.__snitchRequestBackupResendIndex    = 0;
-        global.__snitchRequestBackupFailures       = 0;
-
         if (SNITCH_REQUEST_BACKUP_ENABLE && __SNITCH_HTTP_NEEDED)
         {
             var _lsoadedManifest = false;