continued documenting the code #16

new/AutoItInterpreter/Runtime/AU3Thread.cs

@@ -8,6 +8,7 @@
 
 namespace Unknown6656.AutoIt3.Runtime;
 
+
 /// <summary>
 /// Represents an AutoIt execution thread. The thread consists of multiple call frames which in term represent function invocations.
 /// </summary>
@@ -52,6 +53,9 @@ public bool IsRunning
     /// </summary>
     public ScriptFunction? CurrentFunction => CurrentFrame?.CurrentFunction;
 
+    /// <summary>
+    /// The variable scope associated with the current thread. This might be either a reference to the global variable scope or the variable scope of the current call stack frame.
+    /// </summary>
     public VariableScope CurrentVariableResolver => CurrentFrame?.VariableResolver ?? Interpreter.VariableResolver;
 
     /// <summary>

new/AutoItInterpreter/Runtime/COMConnector.cs

@@ -10,6 +10,7 @@
 
 namespace Unknown6656.AutoIt3.Runtime;
 
+
 public sealed class COMConnector
     : ExternalServiceConnector<COMConnector>
     , ICOMResolver<Variant>

new/AutoItInterpreter/Runtime/CallFrame.cs

@@ -27,6 +27,7 @@
 
 namespace Unknown6656.AutoIt3.Runtime;
 
+
 // TODO : covariant return for 'CurrentFunction'
 
 /// <summary>
@@ -167,13 +168,28 @@ internal FunctionReturnValue Execute(Variant[] args)
     /// <returns>The functions return value or execution error.</returns>
     public FunctionReturnValue Call(ScriptFunction function, Variant[] args) => CurrentThread.Call(function, args, (this as AU3CallFrame)?.InterpreterRunContext ?? InterpreterRunContext.Regular);
 
+    /// <summary>
+    /// Manually sets the value of the <c>@error</c> macro (and optionally <c>@extended</c>).
+    /// See <see href="https://www.autoitscript.com/autoit3/docs/functions/SetError.htm"/>.
+    /// </summary>
+    /// <param name="error">The value to be assigned to the AutoIt macro <c>@error</c>.</param>
+    /// <param name="extended">The value to be assigned to the AutoIt macro <c>@extended</c>.</param>
+    /// <param name="return">The value to be returned by this function (default is <see cref="Variant.Null"/>).</param>
+    /// <returns>The return value, as specified by <paramref name="return"/>.</returns>
     public Variant SetError(int error, Variant? extended = null, in Variant @return = default)
     {
         Interpreter.ErrorCode = error;
 
         return SetExtended(extended, in @return);
     }
 
+    /// <summary>
+    /// Manually sets the value of the <c>@extended</c> macro.
+    /// See <see href="https://www.autoitscript.com/autoit3/docs/functions/SetExtended.htm"/>.
+    /// </summary>
+    /// <param name="extended">The value to be assigned to the AutoIt macro <c>@extended</c>.</param>
+    /// <param name="return">The value to be returned by this function (default is <see cref="Variant.Null"/>).</param>
+    /// <returns>The return value, as specified by <paramref name="return"/>.</returns>
     public Variant SetExtended(Variant? extended, in Variant @return = default)
     {
         Interpreter.ExtendedValue = extended ?? Variant.Null;
@@ -291,10 +307,19 @@ public sealed class AU3CallFrame
     private readonly List<(SourceLocation LineLocation, string LineContent)> _line_cache;
 
 
+    /// <summary>
+    /// Returns the currently executed AutoIt function.
+    /// </summary>
     public override AU3Function CurrentFunction { get; }
 
+    /// <summary>
+    /// Returns the return value of the most recently executed statement.
+    /// </summary>
     public FunctionReturnValue LastStatementValue { get; private set; }
 
+    /// <summary>
+    /// Returns the interpreter run context of the current stack frame.
+    /// </summary>
     public InterpreterRunContext InterpreterRunContext { get; }
 
     /// <summary>

new/AutoItInterpreter/Runtime/Function.cs

@@ -21,6 +21,9 @@ public abstract class ScriptFunction
 {
     internal const string GLOBAL_FUNC = "$global";
 
+    /// <summary>
+    /// A collection of reserved function names.
+    /// </summary>
     public static readonly string[] RESERVED_NAMES =
     {
         "_", "$_", VARIABLE.Discard.Name, "$GLOBAL", "GLOBAL", "STATIC", "CONST", "DIM", "REDIM", "ENUM", "STEP", "LOCAL", "FOR", "IN",
@@ -30,16 +33,31 @@ public abstract class ScriptFunction
     };
 
 
+    /// <summary>
+    /// The name of the current function.
+    /// </summary>
     public string Name { get; }
 
+    /// <summary>
+    /// The script which defines the current function.
+    /// </summary>
     public ScannedScript Script { get; }
 
+    /// <summary>
+    /// The metadata associated with the current function.
+    /// </summary>
     public Metadata Metadata { get; init; } = Metadata.Default;
 
+    /// <summary>
+    /// The source location, at which the current function has been defined.
+    /// </summary>
     public abstract SourceLocation Location { get; }
 
     public abstract (int MinimumCount, int MaximumCount) ParameterCount { get; }
 
+    /// <summary>
+    /// Indicates whether the current function is the global main function (see <see cref="GLOBAL_FUNC"/>).
+    /// </summary>
     public bool IsMainFunction => Name.Equals(GLOBAL_FUNC, StringComparison.OrdinalIgnoreCase);