Added XML documentation to some internals to help with maintainability.

Author: RyanLamansky

SqlServerSimulator/Collation.cs

@@ -1,5 +1,8 @@
 namespace SqlServerSimulator;
 
+/// <summary>
+/// The SQL Server equivalent to .NET's <see cref="IComparer{T}"/> for strings.
+/// </summary>
 internal abstract class Collation : IComparer<string>, IEqualityComparer<string>
 {
     private protected Collation()

SqlServerSimulator/DataType.cs

@@ -4,6 +4,9 @@
 
 namespace SqlServerSimulator;
 
+/// <summary>
+/// Bridges .NET's native types, the various <see cref="DbType"/>s, and SQL Server's actual behavior.
+/// </summary>
 internal abstract class DataType
 {
     private protected DataType()

SqlServerSimulator/Extensions.cs

@@ -5,33 +5,44 @@ namespace SqlServerSimulator;
 
 static class Extensions
 {
+    /// <summary>
+    /// Moves to the next item in an enumeration (if possible) and transfers <see cref="IEnumerator{T}.Current"/> to <paramref name="current"/>.
+    /// </summary>
+    /// <typeparam name="T">The type of enumeration.</typeparam>
+    /// <param name="enumerator">The enumerator to advance.</param>
+    /// <param name="current">Receives the <see cref="IEnumerator{T}.Current"/> value, or the types default if advancement isn't possible.</param>
+    /// <returns>True if the enumerator was advanced, otherwise false.</returns>
     public static bool TryMoveNext<T>(this IEnumerator<T> enumerator, [NotNullWhen(true)] out T? current)
     {
         bool moved;
         current = (moved = enumerator.MoveNext()) ? enumerator.Current : default;
         return moved;
     }
 
+    /// <summary>
+    /// Returns the next token in the enumeration, throwing an exception if the end was reached instead.
+    /// </summary>
+    /// <param name="enumerator">The enumerator to advance.</param>
+    /// <returns>The next token.</returns>
+    /// <exception cref="SimulatedSqlException">Incorrect syntax near '{token}'.</exception>
     public static Parser.Token RequireNext(this IEnumerator<Parser.Token> enumerator)
     {
         Debug.Assert(enumerator.Current is not null);
         var previous = enumerator.Current;
         return enumerator.MoveNext() ? enumerator.Current : throw SimulatedSqlException.SyntaxErrorNear(previous);
     }
 
+    /// <summary>
+    /// Returns the next token in the enumeration, throwing an exception if the end was reached instead or the token is the wrong type.
+    /// </summary>
+    /// <param name="enumerator">The enumerator to advance.</param>
+    /// <returns>The next token.</returns>
+    /// <exception cref="SimulatedSqlException">Incorrect syntax near '{token}'.</exception>
     public static T RequireNext<T>(this IEnumerator<Parser.Token> enumerator)
         where T : Parser.Token
     {
         Debug.Assert(enumerator.Current is not null);
         var previous = enumerator.Current;
-
-        if (enumerator.MoveNext())
-        {
-            var current = enumerator.Current as T;
-            if (current is not null)
-                return current;
-        }
-
-        throw SimulatedSqlException.SyntaxErrorNear(previous);
+        return enumerator.MoveNext() && enumerator.Current is T current ? current : throw SimulatedSqlException.SyntaxErrorNear(previous);
     }
 }

SqlServerSimulator/Parser/Expression.cs

@@ -3,14 +3,31 @@
 
 namespace SqlServerSimulator.Parser;
 
+/// <summary>
+/// Contains the logic described by a SQL command and computes its results.
+/// </summary>
 internal abstract class Expression
 {
     private protected Expression()
     {
     }
 
+    /// <summary>
+    /// A name or alias associated with an expression.
+    /// Anonymous expressions return <see cref="string.Empty"/>.
+    /// </summary>
     public virtual string Name => string.Empty;
 
+    /// <summary>
+    /// Converts the tokens from a command into a single expression.
+    /// </summary>
+    /// <param name="simulation">Simulation shared context.</param>
+    /// <param name="tokens">The sequence of command tokens. This will be advanced to the end of the expression.</param>
+    /// <param name="token">Retains the most recently provided token from <paramref name="tokens"/>.</param>
+    /// <param name="getVariableValue">Provides the value to any variable included alongside the command.</param>
+    /// <returns>The parsed expression.</returns>
+    /// <exception cref="SimulatedSqlException">A variety of messages are possible for various problems with the command.</exception>
+    /// <exception cref="NotSupportedException">A condition was encountered that may be valid but can't currently be parsed.</exception>
     public static Expression Parse(Simulation simulation, IEnumerator<Token> tokens, ref Token? token, Func<string, object?> getVariableValue)
     {
         Expression? expression = null;
@@ -131,6 +148,11 @@ public static Expression Parse(Simulation simulation, IEnumerator<Token> tokens,
         return expression;
     }
 
+    /// <summary>
+    /// Runs the expression, returning its result.
+    /// </summary>
+    /// <param name="getColumnValue">Provides the value for a column.</param>
+    /// <returns>The result of the expression.</returns>
     public abstract object? Run(Func<List<string>, object?> getColumnValue);
 
 #if DEBUG
@@ -144,6 +166,11 @@ public static Expression Parse(Simulation simulation, IEnumerator<Token> tokens,
         new("abs", (simulation, tokens, ref token, getVariableValue) => new AbsoluteValue(Expression.Parse(simulation, tokens, ref token, getVariableValue))),
         ]);
 
+    /// <summary>
+    /// An expression that has been given a name, such as with `as`.
+    /// </summary>
+    /// <param name="expression">The expression to be named.</param>
+    /// <param name="name">The name of the expression, exposed via the <see cref="Name"/> property.</param>
     private sealed class NamedExpression(Expression expression, string name) : Expression
     {
         private readonly Expression expression = expression;
@@ -156,13 +183,11 @@ private sealed class NamedExpression(Expression expression, string name) : Expre
 
         public override object? Run(Func<List<string>, object?> getColumnValue) => this.expression.Run(getColumnValue);
 
-#if DEBUG
         /// <summary>
         /// Transfers the name to an outer expression.
         /// </summary>
         /// <param name="destination">The expression wrapping this<see cref="NamedExpression"/>.</param>
         /// <returns>A new <see cref="NamedExpression"/> wrapping <paramref name="destination"/> using <see cref="Name"/>.</returns>
-#endif
         public NamedExpression TransferName(Expression destination)
         {
 #if DEBUG
@@ -268,6 +293,10 @@ public sealed class Reference(Name name) : Expression
 #endif
     }
 
+    /// <summary>
+    /// Encapsulates the SQL DATALENGTH command: https://learn.microsoft.com/en-us/sql/t-sql/functions/datalength-transact-sql
+    /// </summary>
+    /// <param name="source">Provides the value to be processed.</param>
     public sealed class DataLength(Expression source) : Expression
     {
         private readonly Expression source = source;
@@ -284,6 +313,10 @@ public sealed class DataLength(Expression source) : Expression
 #endif
     }
 
+    /// <summary>
+    /// Encapsulates the SQL ABS command: https://learn.microsoft.com/en-us/sql/t-sql/functions/abs-transact-sql
+    /// </summary>
+    /// <param name="source">Provides the value to be processed.</param>
     public sealed class AbsoluteValue(Expression source) : Expression
     {
         private readonly Expression source = source;

SqlServerSimulator/Parser/Selection.cs

@@ -2,12 +2,26 @@
 
 namespace SqlServerSimulator.Parser;
 
+/// <summary>
+/// Manages the higher-level logic to convert a sequence of command tokens into tabular results.
+/// </summary>
 internal sealed class Selection
 {
     internal readonly SimulatedResultSet Results;
 
     private Selection(SimulatedResultSet results) => this.Results = results;
 
+    /// <summary>
+    /// Creates a <see cref="Selection"/> from a series of tokens.
+    /// </summary>
+    /// <param name="simulation">Simulation shared context.</param>
+    /// <param name="tokens">The sequence of command tokens. This will be advanced to the end of the expression.</param>
+    /// <param name="token">Retains the most recently provided token from <paramref name="tokens"/>.</param>
+    /// <param name="getVariableValue">Provides the value to any variable included alongside the command.</param>
+    /// <param name="depth">The current depth of recursed selection, such as with derived tables. 0 for the top-level SELECT.</param>
+    /// <returns>The prepared command.</returns>
+    /// <exception cref="SimulatedSqlException">A variety of messages are possible for various problems with the command.</exception>
+    /// <exception cref="NotSupportedException">A condition was encountered that may be valid but can't currently be parsed.</exception>
     public static Selection Parse(Simulation simulation, IEnumerator<Token> tokens, ref Token? token, Func<string, object?> getVariableValue, uint depth)
     {
         token = tokens.RequireNext();

SqlServerSimulator/Parser/Token.cs

@@ -1,5 +1,8 @@
 namespace SqlServerSimulator.Parser;
 
+/// <summary>
+/// Describes a single token in a SQL command.
+/// </summary>
 abstract class Token
 {
     private protected Token()

SqlServerSimulator/Parser/Tokenizer.cs

@@ -3,8 +3,14 @@
 
 namespace SqlServerSimulator.Parser;
 
+/// <summary>
+/// Specializes in refining a SQL command string into sequence of <see cref="Token"/> instances.
+/// </summary>
 static class Tokenizer
 {
+    /// <summary>
+    /// Helps the tokenizer keep track of what it's doing.
+    /// </summary>
     enum State
     {
         None,
@@ -17,6 +23,13 @@ enum State
         Numeric
     }
 
+    /// <summary>
+    /// Refines a SQL command string into sequence of <see cref="Token"/> instances.
+    /// </summary>
+    /// <param name="command">The command to tokenize.</param>
+    /// <returns>An enumeration of <paramref name="command"/>'s tokens.</returns>
+    /// <exception cref="InvalidOperationException">ExecuteReader: CommandText property has not been initialized.</exception>
+    /// <exception cref="NotSupportedException">An unsupported pattern was found in the command.</exception>
     public static IEnumerable<Token> Tokenize(string? command)
     {
         if (string.IsNullOrEmpty(command))
@@ -272,6 +285,11 @@ static bool TryGetNext(this CharEnumerator enumerator, out char c, ref int index
         return false;
     }
 
+    /// <summary>
+    /// When true, the state is some variant of a quoted or delimited string.
+    /// </summary>
+    /// <param name="state">The state to check.</param>
+    /// <returns>True if the string is delimited, otherwise false.</returns>
     static bool IsQuotedString(this State state) => state switch
     {
         State.BracketDelimitedString or State.SingleQuotedString or State.DoubleQuotedString => true,