continued adding XML doc comments #16

new/AutoItInterpreter/GithubUpdater.cs

@@ -16,12 +16,25 @@
 
 namespace Unknown6656.AutoIt3;
 
+
+/// <summary>
+/// An enumeration of known GitHub updater modes.
+/// </summary>
 public enum GithubUpdaterMode
 {
+    /// <summary>
+    /// Indicates that the newest version should only be fetched from GitHub if it is marked as "release".
+    /// </summary>
     ReleaseOnly,
+    /// <summary>
+    /// Indicates that the newest version should be fetched from GitHub, even if it is marked as "beta".
+    /// </summary>
     IncludeBetaVersions,
 }
 
+/// <summary>
+/// A class managing software updates by fetching the newest releases from GitHub.
+/// </summary>
 public sealed class GithubUpdater
 {
     private Release[] _releases;
@@ -42,11 +55,21 @@ public sealed class GithubUpdater
     public Release? LatestReleaseAvailable => _releases.FirstOrDefault();
 
 
-    public GithubUpdater(Telemetry telemetry)
+    /// <summary>
+    /// Creates a new instance of the GitHub software updater.
+    /// </summary>
+    /// <param name="telemetry">Reference to the telemetry instance for this application.</param>
+    internal GithubUpdater(Telemetry telemetry)
         : this(telemetry, __module__.Author, __module__.RepositoryName)
     {
     }
 
+    /// <summary>
+    /// Creates a new instance of the GitHub software updater.
+    /// </summary>
+    /// <param name="telemetry">Reference to the telemetry instance for this application.</param>
+    /// <param name="repo_author">Name of the GitHub repository author/owner/organization (user handle, not canonical name).</param>
+    /// <param name="repo_name">Name of the GitHub repository (URN name, not canonical name).</param>
     public GithubUpdater(Telemetry telemetry, string repo_author, string repo_name)
     {
         Client = new GitHubClient(new ProductHeaderValue($"{__module__.Author}.{__module__.RepositoryName}", __module__.InterpreterVersion?.ToString()));

new/AutoItInterpreter/SourceLocation.cs

@@ -1,11 +1,15 @@
-using System.IO;
+using System.IO;
 using System;
 
 using Unknown6656.AutoIt3.Localization;
 using Unknown6656.AutoIt3.CLI;
 
 namespace Unknown6656.AutoIt3;
 
+
+/// <summary>
+/// Represents the location of a line of code inside a (usually known) source file.
+/// </summary>
 public readonly struct SourceLocation
     : IEquatable<SourceLocation>
     , IComparable<SourceLocation>
@@ -41,11 +45,22 @@ public readonly struct SourceLocation
     public bool IsSingleLine => EndLineNumber == StartLineNumber;
 
 
+    /// <summary>
+    /// Creates a new instance of <see cref="SourceLocation"/> using the file path (local or remote), as well as the zero-based line number.
+    /// </summary>
+    /// <param name="file">File path (may also be a remote or non-existent/invalid file path).</param>
+    /// <param name="line">Zero-based line number (i.e. a value of <c>0</c> represents the first line in the specified file).</param>
     public SourceLocation(string file, int line)
         : this(file, line, line)
     {
     }
 
+    /// <summary>
+    /// Creates a new instance of <see cref="SourceLocation"/> using the file path (local or remote), as well as the zero-based start and end line number.
+    /// </summary>
+    /// <param name="file">File path (may also be a remote or non-existent/invalid file path).</param>
+    /// <param name="start">Zero-based start line number (i.e. a value of <c>0</c> represents the first line in the specified file).</param>
+    /// <param name="end">Zero-based end line number. This value must be greater or equals to <paramref name="start"/>.</param>
     public SourceLocation(string file, int start, int end)
     {
         if (start > end)

new/AutoItInterpreter/Telemetry.cs

@@ -13,6 +13,10 @@
 
 namespace Unknown6656.AutoIt3;
 
+
+/// <summary>
+/// An enumeration of known telemetry and performance measurement categories.
+/// </summary>
 public enum TelemetryCategory
 {
     ProgramRuntimeAndPrinting,
@@ -58,6 +62,11 @@ public enum TelemetryCategory
     COMConnection,
 }
 
+/// <summary>
+/// Class containing methods for telemetry operations and the measurement of performance.
+/// <para/>
+/// Note: This does not imply that recorded performance data will be transmitted to an outside server!
+/// </summary>
 public sealed class Telemetry
 {
     private readonly List<(DateTime timestamp, double cpu_total, double cpu_user, double cpu_kernel, long ram_used)> _performance_measurements = new();
@@ -248,6 +257,8 @@ public TelemetryTimingsNode AddChild(string name, TimeSpan[] timings)
         return node;
     }
 
+
+    // TODO : refactor telemetry tree generation
     public static TelemetryTimingsNode FromTelemetry(Telemetry telemetry)
     {
         TimeSpan[] get_timings(params TelemetryCategory[] cat) => cat.SelectMany(c => telemetry.Timings[c]).ToArray();

new/AutoItParser/Cleanup.fs

@@ -159,6 +159,7 @@ module Cleanup =
         | AnyExpression(Binary(Member membr, EqualCaseInsensitive, source)) -> (MemberAssignemnt membr, Assign, source)
         | AnyExpression e -> (VariableAssignment VARIABLE.Discard, Assign, e)
         | AssignmentExpression e -> e
+        // TODO : cover missing expression types
         |> DecomposeAssignmentExpression
         |> FoldAssignment
         |> fun (target, _, expr) -> struct(target, expr)