Improve context documentation and examples

Author: Elektryk-Andrzej

Code/Builders/Builder.cs

@@ -1676,9 +1676,18 @@ private static void CreateSerMethodInfo()
             .OrderBy(keyword => keyword.KeywordName)
             .ToDictionary(keyword => keyword.KeywordName, object (keyword) => new
             {
-                syntax = $"{keyword.KeywordName} {string.Join(" ", keyword.Arguments)}".TrimEnd(),
+                syntax = keyword.Usage,
+                usage = keyword.Usage,
                 description = keyword.Description,
-                arguments = keyword.Arguments,
+                arguments = keyword.Arguments.Select(argument => argument.Syntax).ToArray(),
+                argumentDetails = keyword.Arguments.Select(argument => new
+                {
+                    syntax = argument.Syntax,
+                    description = argument.Description,
+                    inputDescription = argument.InputDescription,
+                    optional = argument.IsOptional,
+                    consumesRemainingValues = argument.ConsumesRemainingValues
+                }).ToArray(),
                 example = keyword.Example,
                 isStatement = keyword is StatementContext,
                 extendsSignal = (keyword as IStatementExtender)?.Extends.ToString(),

Code/ContextSystem/BaseContexts/Context.cs

@@ -9,11 +9,15 @@ public abstract class Context
 {
     public required Script Script { get; set; } = null!;
 
+    public virtual string Usage => this is SER.Code.ContextSystem.Interfaces.IKeywordContext keyword
+        ? $"{keyword.KeywordName} {string.Join(" ", keyword.Arguments.Select(argument => argument.Syntax))}".TrimEnd()
+        : FriendlyName;
+
     public abstract string FriendlyName { get; }
 
     public abstract TryAddTokenRes TryAddToken(BaseToken token);
 
     public abstract Result VerifyCurrentState();
 
     public abstract override string ToString();
-}
+}

Code/ContextSystem/BaseContexts/LoopContext.cs

@@ -11,22 +11,21 @@ public abstract class LoopContext : StatementContext, IKeywordContext
 
     protected bool ReceivedContinue;
 
-    protected abstract string? Usage { get; }
+    protected abstract string? DetailedUsage { get; }
 
     public sealed override string FriendlyName => $"'{KeywordName}' loop statement";
     public Dictionary<IExtendableStatement.Signal, StatementContext> RegisteredSignals { get; } = [];
 
     public abstract string KeywordName { get; }
     public abstract string Description { get; }
-    public abstract string[] Arguments { get; }
+    public abstract ContextArgument[] Arguments { get; }
 
     public string Example => ExampleHandler.GetExample($"{KeywordName}KeywordExample") ??
-                             $"""
-                              {Usage}
+                              $"""
+                               {DetailedUsage}
 
-                              # ========================================
-                              # "break" and "continue" keywords work as usual and you are free to use them inside "{KeywordName}" loops
-                              """;
+                               # Use break to leave the loop or continue to skip to its next iteration.
+                               """;
 
     protected override void OnReceivedControlMessageFromChild(ParentContextControlMessage msg)
     {

Code/ContextSystem/Contexts/Control/AttemptStatement.cs

@@ -20,14 +20,17 @@ public class AttemptStatement : StatementContext, IExtendableStatement, IKeyword
         "Runs everything inside the statement, and if something throws an exception (error), the error will not " +
         "terminate the script. If there is an 'on_error' statement, it will be executed.";
 
-    public string[] Arguments => [];
+    public ContextArgument[] Arguments => [];
     public string Example =>
         """
         &collection = Coll.Empty
-        # swallows the error (doesn't stop the script)
         attempt
             Print {Coll.Fetch &collection 2}
-            # throws because there's nothing at index 2
+        end
+
+        # The error is handled by on_error when one is present.
+        on_error with $message
+            Print "Handled: {$message}"
         end
         """;
 

Code/ContextSystem/Contexts/Control/BreakKeyword.cs

@@ -15,30 +15,18 @@ public class BreakKeyword : StandardContext, IKeywordContext
         "Makes a given loop or function (that the 'break' keyword is inside) act as it has completely ended its execution " +
         "(\"breaks\" free from the loop/function)";
 
-    public string[] Arguments => [];
+    public ContextArgument[] Arguments => [];
 
     public string Example =>
-          """
-          # for example:
-          forever
-              wait 1s
-              
-              Print "attempting to leave forever loop"
-              if {Chance 20%}
-                  break
-              end
-          end
-
-          func Test
-              if {Chance 20%}
-                  break
-              end
-              
-              Print "this will not run because the 'break' keyword was used"
-          end
-
-          run Test
-          """;
+        """
+        # the execution will "break" free after the third iteration
+        repeat 10 with $iteration
+            if {$iteration is 3}
+                break
+            end
+            Print "iteration {$iteration}"
+        end
+        """;
 
     public override TryAddTokenRes TryAddToken(BaseToken token)
     {
@@ -54,4 +42,4 @@ protected override void Execute()
     {
         ParentContext?.SendControlMessage(new Break());
     }
-}
+}

Code/ContextSystem/Contexts/Control/ChanceStatement.cs

@@ -22,8 +22,21 @@ public class ChanceStatement : StatementContext, IExtendableStatement, IKeywordC
     public Dictionary<IExtendableStatement.Signal, StatementContext> RegisteredSignals { get; } = [];
     public string KeywordName => "chance";
     public string Description => "This statement will execute with the provided chance.";
-    public string[] Arguments => ["$chance"];
-    public string? Example => null;
+    public ContextArgument[] Arguments => [ContextArgument.Required(
+        "$chance", "Probability that the body will execute.",
+        "A number from 0 to 1, where 1 is 100%.")];
+    public string Example =>
+        """
+        chance 25%
+            Print "This happens about one time in four."
+        end
+
+        # The chance can also come from a value expression.
+        $probability = 50%
+        chance $probability
+            Print "This happens about half the time."
+        end
+        """;
 
     public override TryAddTokenRes TryAddToken(BaseToken token)
     {

Code/ContextSystem/Contexts/Control/ElifStatement.cs

@@ -23,8 +23,19 @@ public class ElifStatement : StatementContext, IStatementExtender, IExtendableSt
     public string KeywordName => "elif";
     public string Description =>
         "If the statement above it didn't execute, 'elif' statement will try to execute if the provided condition is met.";
-    public string[] Arguments => ["$condition"];
-    public string? Example => null;
+    public ContextArgument[] Arguments => [ContextArgument.Required(
+        "$condition", "Expression checked when the preceding branch did not execute.",
+        "A boolean expression; values and method calls may be grouped with braces.")];
+    public string Example =>
+        """
+        if {@sender -> role} is "ClassD"
+            Print "You are a Class-D."
+        elif {@sender -> role} is "Scientist"
+            Print "You are a scientist."
+        else
+            Print "You have another role."
+        end
+        """;
 
     public IExtendableStatement.Signal Extends => IExtendableStatement.Signal.DidntExecute;
 

Code/ContextSystem/Contexts/Control/ElseStatement.cs

@@ -14,10 +14,15 @@ public class ElseStatement : StatementContext, IStatementExtender, IKeywordConte
     public string KeywordName => "else";
     public string Description =>
         "If the statement above it didn't execute, 'else' statement will execute instead.";
-    public string[] Arguments => [];
-    public string? Example => null;
-
-    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+    public ContextArgument[] Arguments => [];
+    public string Example =>
+        """
+        if {@sender -> team} is "SCPs"
+            Reply "You are an SCP"
+        else
+            Reply "You are not an SCP"
+        end
+        """;
 
     public IExtendableStatement.Signal Extends => IExtendableStatement.Signal.DidntExecute;
 

Code/ContextSystem/Contexts/Control/EndKeyword.cs

@@ -12,8 +12,13 @@ public class EndKeyword : StandardContext, IKeywordContext
     public override string FriendlyName => "'end' keyword";
     public string KeywordName => "end";
     public string Description => "Ends the current statement's body.";
-    public string[] Arguments => [];
-    public string? Example => null;
+    public ContextArgument[] Arguments => [];
+    public string Example =>
+        """
+        if {@sender -> role} is "ClassD"
+            Print "This block ends here."
+        end
+        """;
 
     ////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
@@ -30,4 +35,4 @@ public override Result VerifyCurrentState()
     protected override void Execute()
     {
     }
-}
+}

Code/ContextSystem/Contexts/Control/IfStatement.cs

@@ -22,8 +22,19 @@ public class IfStatement : StatementContext, IExtendableStatement, IKeywordConte
     public Dictionary<IExtendableStatement.Signal, StatementContext> RegisteredSignals { get; } = [];
     public string KeywordName => "if";
     public string Description => "This statement will execute only if the provided condition is met.";
-    public string[] Arguments => ["$condition"];
-    public string? Example => null;
+    public ContextArgument[] Arguments => [ContextArgument.Required(
+        "$condition", "Expression that must evaluate to true for the body to run.",
+        "A boolean expression; values and method calls may be grouped with braces.")];
+    public string Example =>
+        """
+        if {@sender -> isAlive}
+            Print "You are still alive."
+        end
+
+        if {AmountOf @all} > 0
+            Print "There is at least one player online."
+        end
+        """;
 
     public override TryAddTokenRes TryAddToken(BaseToken token)
     {