Merge pull request #147 from jacz24/Documentation

Multiple commits for documentation mainly inside utils

Author: Torwent

osrs/interfaces/mainscreen/shop.simba

@@ -50,15 +50,19 @@ You have 2 ways of getting the shop item slots, a static one:
 ```pascal
 ShowOnTarget(Shop.SlotBoxes);
 ```
-
+```{figure} ../../images/shop_static_slots.png
+The shop static slots.
+```
 
 And a dynamic one:
 ```pascal
 ShowOnTarget(Shop.FindItemBoundaries());
 ```
+```{figure} ../../images/shop_item_boundaries.png
+The shop "dynamic" slots.
+```
 
 There are use cases for both, internally, `Shop.FindItemBoundaries` is usually used.
-
 *)
 function TRSShop.FindItemBoundaries(): TBoxArray;
 var

utils/assets.simba

@@ -6,6 +6,10 @@ Responsible for managing assets that WaspLib requires to run.
 {$INCLUDE_ONCE WaspLib/utils.simba}
 
 type
+(*
+## TWLAssets
+Record for managing WaspLib asset downloads and updates.
+*)
   TWLAssets = record
     JSON: TJSONObject;
     Queue: TStringArray;

utils/config.simba

@@ -62,6 +62,10 @@ begin
   TJSONParser(Self.Data).Save(Self.Path, [EJSONFormatOption.USE_TABS, EJSONFormatOption.SINGLE_LINE_ARR], 1);
 end;
 
+(*
+## TConfigINI
+Type responsible for dealing with INI configuration files.
+*)
 type
   TConfigINI  = record
     Path: String;

utils/imagecompare.simba

@@ -1,6 +1,14 @@
+(*
+# Image Compare
+Utilities for comparing images using template matching.
+*)
 {$DEFINE WL_IMAGECOMPARE_INCLUDED}
 
 type
+(*
+## TImageMatch
+Record storing image match result with position and similarity score.
+*)
   TImageMatch = record
     Index: Integer;
     Box: TBox;
@@ -11,12 +19,23 @@ type
 
   TImageCompareFilter = procedure(constref image, template: TImage) of object;
 
+(*
+## TImageCompareUtils
+Utilities for comparing and matching images with optional cleaning and alignment.
+*)
   TImageCompareUtils = record
     Clean: procedure (image, template: TImage) of object;
     Align: function (image, template: TImage): Boolean of object;
     Filter: TImageCompareFilter;
   end;
 
+(*
+## TImageCompareUtils.Compare
+```pascal
+function TImageCompareUtils.Compare(image, template: TImage; var similarity: Single): Boolean;
+```
+Compares two images and returns True if similarity threshold is met.
+*)
 function TImageCompareUtils.Compare(image, template: TImage; var similarity: Single): Boolean;
 var
   match: Single;
@@ -57,7 +76,13 @@ begin
   Result := Self.Compare(image, template, similarity);
 end;
 
-
+(*
+## TImageCompareUtils.FindMatch
+```pascal
+function TImageCompareUtils.FindMatch(image: TImage; bounds: TBox; out match: TImageMatch): Boolean;
+```
+Finds the best match for an image within specified bounds using template matching.
+*)
 function TImageCompareUtils.FindMatch(image: TImage; bounds: TBox; out match: TImageMatch): Boolean;
 var
   container: TImage;

utils/logger.simba

@@ -1,15 +1,39 @@
+(*
+# Logger
+Logging utilities for WaspLib scripts.
+*)
+
 {$DEFINE WL_LOGGER_INCLUDED}
 {$INCLUDE_ONCE WaspLib/utils.simba}
 
 type
+(*
+## ELogLevel
+```pascal
+ELogLevel = enum(SUCCESS, WARN, ERROR);
+```
+Enum representing log message severity levels.
+*)
   ELogLevel = enum(SUCCESS, WARN, ERROR);
 
+(*
+## TLogger
+Record for managing script logging to files and console output.
+*)
   TLogger = record
     Name, Path, PreviousMessage: String;
     TimeRunning: TStopwatch;
     IsSetup, RepeatedMessages: Boolean;
   end;
 
+(*
+## Logger.Init
+```pascal
+procedure TLogger.Init();
+```
+Initializes the logger, creating the log directory and file.
+Called automatically at script start.
+*)
 procedure TLogger.Init();
 var
   files: TStringArray;
@@ -46,6 +70,18 @@ begin
   Self.TimeRunning.Start();
 end;
 
+(*
+## Logger.Setup
+```pascal
+procedure TLogger.Setup(name: String = '');
+```
+Configures the logger with a script name. Creates a dedicated log directory.
+
+Example:
+```pascal
+Logger.Setup('MyScript');
+```
+*)
 procedure TLogger.Setup(name: String = '');
 var
   old: String;
@@ -77,10 +113,24 @@ begin
   FileAppend(Self.Path, line + LINE_SEP);
 end;
 
-
 var
+(*
+## Logger variable
+Global {ref}`TLogger` variable.
+*)
   Logger: TLogger;
 
+(*
+## GetDebugLn
+```pascal
+function GetDebugLn(text: String; log: Boolean = True): String;
+function GetDebugLn(name, text: String; log: Boolean = True): String; overload;
+function GetDebugLn(text: String; level: ELogLevel; log: Boolean = True): String; overload;
+function GetDebugLn(name, text: String; level: ELogLevel; log: Boolean = True): String; overload;
+```
+Returns a formatted debug string with timestamp.
+Optionally logs to file and applies color formatting based on `level`.
+*)
 function GetDebugLn(text: String; log: Boolean = True): String;
 begin
   Result := GetTimeStamp() + ': ' + text;
@@ -112,6 +162,14 @@ begin
 end;
 
 
+(*
+## Logger.Info
+```pascal
+procedure TLogger.Info(text: String; vars: TVariantArray = []);
+```
+Logs an info message. Duplicate consecutive messages are suppressed unless
+`Logger.RepeatedMessages` is True.
+*)
 procedure TLogger.Info(text: String; vars: TVariantArray = []);
 var
   formatted: String;
@@ -124,6 +182,13 @@ begin
   Self.PreviousMessage := formatted;
 end;
 
+(*
+## Logger.Success
+```pascal
+procedure TLogger.Success(text: String; vars: TVariantArray = []);
+```
+Logs a success message (green colored output).
+*)
 procedure TLogger.Success(text: String; vars: TVariantArray = []);
 var
   formatted: String;
@@ -133,6 +198,13 @@ begin
   WriteLn(GetDebugLn(Self.Name, formatted, ELogLevel.SUCCESS, False));
 end;
 
+(*
+## Logger.Warn
+```pascal
+procedure TLogger.Warn(text: String; vars: TVariantArray = []);
+```
+Logs a warning message (yellow colored output).
+*)
 procedure TLogger.Warn(text: String; vars: TVariantArray = []);
 var
   formatted: String;
@@ -142,6 +214,13 @@ begin
   WriteLn(GetDebugLn(Self.Name, formatted, ELogLevel.WARN, False));
 end;
 
+(*
+## Logger.Error
+```pascal
+procedure TLogger.Error(text: String; vars: TVariantArray = []);
+```
+Logs an error message (red colored output).
+*)
 procedure TLogger.Error(text: String; vars: TVariantArray = []);
 var
   formatted: String;
@@ -151,6 +230,13 @@ begin
   WriteLn(GetDebugLn(Self.Name, formatted, ELogLevel.ERROR, False));
 end;
 
+(*
+## Logger.Exception
+```pascal
+procedure TLogger.Exception(text: String; vars: TVariantArray = []);
+```
+Logs an error message and raises an exception to halt script execution.
+*)
 procedure TLogger.Exception(text: String; vars: TVariantArray = []);
 var
   formatted: String;