Add XML documentation for runtime types and transaction support

Co-authored-by: Thorium <229355+Thorium@users.noreply.github.com>

Author: Copilot

src/SQLProvider.Common/SqlRuntime.Async.fs

@@ -8,8 +8,18 @@ open FSharp.Data.Sql.Common
 open FSharp.Data.Sql.Patterns
 open System.Linq
 
+/// <summary>
+/// Provides asynchronous operations for SQL queries.
+/// Use these functions when you need to execute queries asynchronously to avoid blocking threads.
+/// </summary>
 module AsyncOperations =
 
+    /// <summary>
+    /// Executes a queryable asynchronously and returns the results as a sequence.
+    /// This is useful for executing large queries without blocking the calling thread.
+    /// </summary>
+    /// <param name="s">The queryable to execute</param>
+    /// <returns>A task that yields a sequence of results</returns>
     let executeAsync (s:Linq.IQueryable<'T>) =
         let inline yieldseq (en: IEnumerator<'T>) =
             seq {

src/SQLProvider.Common/SqlRuntime.Common.fs

@@ -16,27 +16,57 @@ open Microsoft.FSharp.Reflection
 open System.Collections.Concurrent
 open System.Runtime.Serialization
 
+/// <summary>
+/// Specifies the database provider type for the SQL type provider.
+/// Each provider has its own specific implementation for SQL generation and data type mapping.
+/// </summary>
 type DatabaseProviderTypes =
+    /// Microsoft SQL Server using SqlClient provider
     | MSSQLSERVER = 0
+    /// SQLite database using System.Data.SQLite or Microsoft.Data.Sqlite
     | SQLITE = 1
+    /// PostgreSQL using Npgsql provider
     | POSTGRESQL = 2
+    /// MySQL using MySql.Data or MySqlConnector provider
     | MYSQL = 3
+    /// Oracle Database using Oracle.ManagedDataAccess provider
     | ORACLE = 4
+    /// Microsoft Access using OleDb provider
     | MSACCESS = 5
+    /// Generic ODBC provider for various databases
     | ODBC = 6
+    /// Firebird database using FirebirdSql.Data.FirebirdClient
     | FIREBIRD = 7
+    /// Microsoft SQL Server with dynamic schema loading
     | MSSQLSERVER_DYNAMIC = 8
+    /// Microsoft SQL Server using SSDT/DacPac for schema
     | MSSQLSERVER_SSDT = 9
+    /// DuckDB using DuckDB.NET provider
     | DUCKDB = 10
+    /// External/custom database provider
     | EXTERNAL = 11
 
-type RelationshipDirection = Children = 0 | Parents = 1
+/// <summary>Specifies the direction for relationship navigation.</summary>
+type RelationshipDirection = 
+    /// Navigate to child records (foreign key relationships)
+    Children = 0
+    /// Navigate to parent records (primary key relationships)
+    | Parents = 1
 
+/// <summary>
+/// Specifies how to handle case sensitivity when generating table and column names.
+/// </summary>
 type CaseSensitivityChange =
+    /// Keep original casing from the database
     | ORIGINAL = 0
+    /// Convert all names to uppercase
     | TOUPPER = 1
+    /// Convert all names to lowercase
     | TOLOWER = 2
 
+/// <summary>
+/// Specifies how to represent nullable database columns in the generated types.
+/// </summary>
 type NullableColumnType =
     /// Nullable types are just Unchecked default. (Old false.)
     | NO_OPTION = 0
@@ -45,7 +75,11 @@ type NullableColumnType =
     /// ValueOption is more performant.
     | VALUE_OPTION = 2
 
+/// <summary>
+/// Specifies the quote character style for ODBC connections when dealing with table and column names containing spaces or special characters.
+/// </summary>
 type OdbcQuoteCharacter =
+    /// Use default quoting for the ODBC driver
     | DEFAULT_QUOTE = 0
     /// MySQL/Postgre style: `alias` 
     | GRAVE_ACCENT = 1
@@ -58,6 +92,10 @@ type OdbcQuoteCharacter =
     /// Single quote: 'alias'
     | APHOSTROPHE = 5 
 
+/// <summary>
+/// Specifies which SQLite library to use for connections.
+/// Different libraries may have different capabilities and platform support.
+/// </summary>
 type SQLiteLibrary =
     /// .NET Framework default
     | SystemDataSQLite = 0
@@ -68,8 +106,16 @@ type SQLiteLibrary =
     /// Microsoft.Data.Sqlite. May support .NET Standard 2.0 contract in the future.
     | MicrosoftDataSqlite = 3
 
+/// <summary>
+/// Contains events for monitoring SQL query execution and debugging.
+/// Use these events to log, debug, or analyze the SQL queries generated by the type provider.
+/// </summary>
 module public QueryEvents =
 
+   /// <summary>
+   /// Contains information about a SQL command being executed, including the command text,
+   /// parameters, and connection information for debugging and monitoring purposes.
+   /// </summary>
    type SqlEventData = {
        /// The text of the SQL command being executed.
        Command: string
@@ -112,8 +158,18 @@ module public QueryEvents =
 
    let private sqlEvent = Event<SqlEventData>()
 
-   /// This event fires immediately before the execution of every generated query. 
+   /// <summary>
+   /// Event that fires immediately before the execution of every generated query. 
    /// Listen to this event to display or debug the content of your queries.
+   /// This is useful for logging, performance monitoring, and debugging SQL generation.
+   /// </summary>
+   /// <example>
+   /// <code>
+   /// QueryEvents.SqlQueryEvent.Add(fun event ->
+   ///     printfn "Executing: %s" event.Command
+   ///     printfn "Parameters: %A" event.Parameters)
+   /// </code>
+   /// </example>
    [<CLIEvent>]
    let SqlQueryEvent = sqlEvent.Publish
 
@@ -150,13 +206,26 @@ module public QueryEvents =
    let internal PublishExpression(e) = expressionEvent.Trigger(e)
 
 [<Struct>]
+/// <summary>
+/// Represents the current state of a database entity for change tracking purposes.
+/// Used internally by the SQL provider to determine what operations need to be performed during SubmitUpdates().
+/// </summary>
 type EntityState =
+    /// Entity has not been modified since it was loaded
     | Unchanged
+    /// Entity is new and should be inserted into the database
     | Created
+    /// Entity has been modified; contains list of changed column names
     | Modified of string list
+    /// Entity is marked for deletion (soft delete)
     | Delete
+    /// Entity has been deleted from the database
     | Deleted
 
+/// <summary>
+/// Specifies how to handle conflicts when inserting records with duplicate primary keys.
+/// Currently supported only on databases that have UPSERT capabilities.
+/// </summary>
 [<Struct>]
 type OnConflict = 
     /// Throws an exception if the primary key already exists (default behaviour).
@@ -168,18 +237,40 @@ type OnConflict =
     /// Currently supported only on PostgreSQL 9.5+
     | DoNothing
 
+/// <summary>
+/// Attribute for mapping entity properties to database columns with different names.
+/// Use this when your database column name differs from your preferred F# property name.
+/// </summary>
+/// <example>
+/// <code>
+/// [&lt;MappedColumn("customer_id")&gt;]
+/// member x.CustomerId = x.GetColumn&lt;int&gt;("customer_id")
+/// </code>
+/// </example>
 type MappedColumnAttribute(name: string) = 
     inherit Attribute()
+    /// Gets the database column name this property maps to
     member x.Name with get() = name
 
+/// <summary>Represents a result set as a sequence of rows, where each row is an array of column name-value pairs.</summary>
 type ResultSet = seq<(string * obj)[]>
+
+/// <summary>Represents different types of result sets that can be returned from stored procedures.</summary>
 type ReturnSetType =
+    /// A single scalar value with name and value
     | ScalarResultSet of string * obj
+    /// A result set with name and data rows
     | ResultSet of string * ResultSet
+
+/// <summary>Represents different types of return values from stored procedures and functions.</summary>
 type ReturnValueType =
+    /// No return value (void)
     | Unit
+    /// A single scalar value
     | Scalar of string * obj
+    /// A single result set
     | SingleResultSet of string * ResultSet
+    /// Multiple result sets
     | Set of seq<ReturnSetType>
 
 /// Interface to hide internal members that are typically not needed by the user
@@ -478,6 +569,11 @@ type SqlEntity(dc: ISqlDataContext, tableName, columns: ColumnLookup, activeColu
                                  override __.ShouldSerializeValue(_) = false })
                |> Seq.cast<PropertyDescriptor> |> Seq.toArray )
 
+/// <summary>
+/// The main interface for SQL data context operations. This interface provides all the core functionality
+/// for querying, creating, updating, and deleting data through the SQL type provider.
+/// Users typically access this through the generated GetDataContext() method.
+/// </summary>
 and ISqlDataContext =
     /// Connection string to database
     abstract ConnectionString           : string
@@ -520,8 +616,12 @@ and ISqlDataContext =
     /// Context meant to be read operations only
     abstract IsReadOnly                 : bool
 
-/// This is publically exposed and used in the runtime
+/// <summary>
+/// Interface implemented by generated types that provide access to the underlying data context.
+/// This allows access to the ISqlDataContext for advanced operations.
+/// </summary>
 type IWithDataContext =
+    /// Gets the underlying SQL data context
     abstract DataContext : ISqlDataContext
 
 /// LinkData is for joins with SelectMany

src/SQLProvider.Common/SqlRuntime.Transactions.fs

@@ -2,24 +2,43 @@ namespace FSharp.Data.Sql.Transactions
 
 open System
 
-/// Corresponds to the System.Transactions.IsolationLevel.
+/// <summary>
+/// Transaction isolation level for database operations.
+/// Corresponds to the System.Transactions.IsolationLevel but provides SQL provider specific functionality.
+/// </summary>
 type IsolationLevel =
+    /// Highest isolation level - transactions are completely isolated from each other
     | Serializable = 0
+    /// Prevents dirty reads and non-repeatable reads, but phantom reads can occur
     | RepeatableRead = 1
+    /// Prevents dirty reads but allows non-repeatable reads and phantom reads (default for most databases)
     | ReadCommitted = 2
+    /// Allows dirty reads, non-repeatable reads, and phantom reads (fastest but least safe)
     | ReadUncommitted = 3
+    /// SQL Server specific - provides statement-level read consistency using versioning
     | Snapshot = 4
+    /// Allows any level of isolation, including overlapping changes (SQL Server specific)
     | Chaos = 5
+    /// Use the default isolation level of the database
     | Unspecified = 6
+    /// Special value to indicate that no transaction should be created
     | DontCreateTransaction = 99
 
+/// <summary>
+/// Configuration options for database transactions.
 /// Corresponds to the System.Transactions.TransactionOptions.
+/// </summary>
 [<Struct>]
 type TransactionOptions = {
+    /// Maximum time the transaction can remain active before timing out
     Timeout : TimeSpan
+    /// The isolation level for the transaction
     IsolationLevel : IsolationLevel
 }
 
+/// <summary>
+/// Utility functions for converting between different transaction isolation level representations.
+/// </summary>
 module TransactionUtils =
     let internal toSystemTransactionsIsolationLevel isolationLevel =
         match isolationLevel with
@@ -32,6 +51,12 @@ module TransactionUtils =
         | IsolationLevel.Unspecified -> System.Transactions.IsolationLevel.Unspecified
         | _ -> failwithf "Unhandled IsolationLevel value: %A." isolationLevel
 
+    /// <summary>
+    /// Converts SQL provider isolation level to System.Data.IsolationLevel.
+    /// Use this when you need to work directly with ADO.NET connection transactions.
+    /// </summary>
+    /// <param name="isolationLevel">The SQL provider isolation level</param>
+    /// <returns>The corresponding System.Data.IsolationLevel</returns>
     let toSystemDataIsolationLevel isolationLevel =
         match isolationLevel with
         | IsolationLevel.Serializable -> System.Data.IsolationLevel.Serializable