Added random Documentation

Author: jacz24

utils/math/random.simba

@@ -1,9 +1,31 @@
+(*
+# Random
+Random number generation utilities and weighted random point functions.
+*)
+
 {$DEFINE WL_RANDOM_INCLUDED}
 
 type
+(*
+## ERandomDir
+Direction bias for random number generation (LEFT, MEAN, RIGHT).
+*)
   ERandomDir = enum(LEFT, MEAN, RIGHT);
+
+(*
+## ERandomDistribution
+Distribution type for random generation (RANDOM or GAUSS).
+*)
   ERandomDistribution = enum(RANDOM, GAUSS);
 
+(*
+## RandomBoolean
+```pascal
+function RandomBoolean(): Boolean;
+function RandomBoolean(probability: Double): Boolean; overload;
+```
+Returns a random boolean. Optionally weighted by probability (0.0-1.0).
+*)
 function RandomBoolean(): Boolean;
 begin
   Result := Boolean(Random(0,1));
@@ -14,6 +36,13 @@ begin
   Result := Random() <= probability;
 end;
 
+(*
+## Sleep (overload)
+```pascal
+procedure Sleep(min, max: UInt32; dir: ERandomDir = ERandomDir.LEFT); overload;
+```
+Sleeps for a random duration between min and max, biased by direction.
+*)
 procedure Sleep(min, max: UInt32; dir: ERandomDir = ERandomDir.LEFT); overload;
 begin
   case dir of
@@ -23,6 +52,13 @@ begin
   end;
 end;
 
+(*
+## TPoint.RandomBetween
+```pascal
+function TPoint.RandomBetween(other: TPoint): TPoint;
+```
+Returns a random point on the line between Self and other.
+*)
 function TPoint.RandomBetween(other: TPoint): TPoint;
 var
   r: Double;
@@ -32,15 +68,26 @@ begin
   Result.Y := Self.Y + Round(r * (other.Y - Self.Y));
 end;
 
-
+(*
+## TPointArray.RandomMean
+```pascal
+function TPointArray.RandomMean(): TPoint;
+```
+Returns a random point from the array, weighted towards the mean.
+*)
 function TPointArray.RandomMean(): TPoint;
 begin
   if Length(Self) = 0 then Exit;
   Result := Self.SortFrom(Self.Mean())[RandomLeft(0, High(Self))];
 end;
 
-
-
+(*
+## TCircle.RandomSkewedPoint
+```pascal
+function TCircle.RandomSkewedPoint(from: TPoint; force: Double = 0.35): TPoint;
+```
+Generates a random point within the circle, skewed towards `from`.
+*)
 function TCircle.RandomSkewedPoint(from: TPoint; force: Double = 0.35): TPoint;
 var
   skewed, rand: TPoint;
@@ -72,7 +119,15 @@ begin
   RandCutoff := cutoff;
 end;
 
-//by [slacky](https://slacky.one/)
+(*
+## TCircle.RandomWeightedPoint
+```pascal
+function TCircle.RandomWeightedPoint(from: TPoint; weight: Single = 10.0; bias: Single = 1): TPoint;
+```
+Generates a random point within the circle, weighted towards `from`.
+
+Credits: [slacky](https://slacky.one/)
+*)
 function TCircle.RandomWeightedPoint(from: TPoint; weight: Single = 10.0; bias: Single = 1): TPoint;
 var
   angle, dist, r1, r2, sum, u, t: Single;
@@ -103,7 +158,13 @@ begin
   Result.Y := Round(u * randY + t * from.Y);
 end;
 
-
+(*
+## TTriangle.RandomSkewedPoint
+```pascal
+function TTriangle.RandomSkewedPoint(from: TPoint; force: Double = 0.35): TPoint;
+```
+Generates a random point within the triangle, skewed towards `from`.
+*)
 function TTriangle.RandomSkewedPoint(from: TPoint; force: Double = 0.35): TPoint;
 var
   c, skewed: TPoint;
@@ -146,7 +207,7 @@ Parameters:
 - bias: Introduces a Gaussian spread around the `from` (higher values = wider spread).
   - bias = 0 gives a purely weighted distribution towards the `from`.
 
-Should expose weight and bias to the user if used as mouse distribution method. weight of 10 might be a little high.
+Should expose weight and bias to the user if used as mouse distribution method.
 
 Credits: [slacky](https://slacky.one/)
 *)
@@ -191,8 +252,15 @@ begin
   end;
 end;
 
+(*
+## TPolygon.RandomPoint
+```pascal
+function TPolygon.RandomPoint(): TPoint;
+```
+Generates a uniformly distributed random point within the polygon.
 
-//by torwent
+Credits: torwent
+*)
 function TPolygon.RandomPoint(): TPoint;
 var
   tris: TTriangleArray;
@@ -220,7 +288,15 @@ begin
   end;
 end;
 
-//by bootie
+(*
+## TPolygon.RandomPointCenter
+```pascal
+function TPolygon.RandomPointCenter(): TPoint;
+```
+Generates a random point within the polygon, weighted towards the center.
+
+Credits: bootie
+*)
 function TPolygon.RandomPointCenter(): TPoint;
 var
   mean: TPoint;
@@ -235,6 +311,13 @@ begin
   until Self.Contains(Result);
 end;
 
+(*
+## TPolygon.RandomSkewedPoint
+```pascal
+function TPolygon.RandomSkewedPoint(from: TPoint): TPoint;
+```
+Generates a random point within the polygon, skewed towards `from`.
+*)
 function TPolygon.RandomSkewedPoint(from: TPoint): TPoint;
 begin
   Result := Self.RandomWeightedPoint(from);
@@ -285,9 +368,9 @@ function TQuad.RandomSkewedPoint(from: TPoint; force: Double = 0.35): TPoint;
 Generates a random point within the bounds of the TQuad, the point generated is skewed towards towards the `from`-point.
 The last parameter `force` defines how much the generated point is to be skewed towards or away from `from` - Expects value in the range 0..2
 
-- force = 0: Result weighs heavily towrads the edge closest to `From`
+- force = 0: Result weighs heavily towards the edge closest to `From`
 - force = 1: Result in the middle of box is most common
-- force = 2: Result weighs heavily towrads the edge furthest away from `From`
+- force = 2: Result weighs heavily towards the edge furthest away from `From`
 *)
 function TQuad.RandomSkewedPoint(from: TPoint; force: Double = 0.35): TPoint;
 var
@@ -324,12 +407,12 @@ end;
 ```pascal
 function TBox.RandomSkewedPoint(from: TPoint; force: Double = 0.35): TPoint;
 ```
-Generates a random point within the bounds of the TBox, the point generated is skewed towards towards the `from`-point.
+Generates a random point within the bounds of the TBox, the point generated is skewed towards the `from`-point.
 The last parameter `force` defines how much the generated point is to be skewed towards or away from `from` - Expects value in the range 0..2
 
-- force = 0: Result weighs heavily towrads the edge closest to `From`
+- force = 0: Result weighs heavily towards the edge closest to `From`
 - force = 1: Result in the middle of box is most common
-- force = 2: Result weighs heavily towrads the edge furthest away from `From`
+- force = 2: Result weighs heavily towards the edge furthest away from `From`
 *)
 function TBox.RandomSkewedPoint(from: TPoint; force: Double = 0.35): TPoint;
 var
@@ -357,7 +440,3 @@ function TBox.RandomWeightedPoint(from: TPoint; weight: Single = 10.0; bias: Sin
 begin
   Result := TPolygon(Self.Corners).RandomWeightedPoint(from, weight, bias);
 end;
-
-
-
-