more docs

Author: KirillKurdyukov

src/Ydb.Sdk/CHANGELOG.md

@@ -1,4 +1,4 @@
-- XML documentation for all public APIs in `Ydb.Sdk`.
+- Added XML documentation for all public APIs in `Ydb.Sdk`.
 - Feat ADO.NET: Added dispose timeout (10 seconds) to `PoolingSessionSource`.
 - Feat ADO.NET: Added `EnableImplicitSession` to support implicit sessions.
 

src/Ydb.Sdk/src/Ado/Schema/YdbTableStats.cs

@@ -1,6 +1,6 @@
 namespace Ydb.Sdk.Ado.Schema;
 
-public class YdbTableStats
+internal class YdbTableStats
 {
     public YdbTableStats(Table.TableStats tableStats)
     {

src/Ydb.Sdk/src/Ado/Transaction/TransactionMode.cs

@@ -10,7 +10,7 @@ namespace Ydb.Sdk.Ado;
 /// for database operations within a transaction.
 /// 
 /// For more information about YDB transaction modes, see:
-/// <see href="https://ydb.tech/docs/en/concepts/transactions">YDB Transactions Documentation</see>
+/// <see href="https://ydb.tech/docs/en/concepts/transactions">YDB Transactions Documentation</see>.
 /// </remarks>
 public enum TransactionMode
 {

src/Ydb.Sdk/src/Ado/YdbConnectionStringBuilder.cs

@@ -15,6 +15,9 @@ namespace Ydb.Sdk.Ado;
 /// <remarks>
 /// YdbConnectionStringBuilder provides strongly-typed properties for building YDB connection strings.
 /// It supports all standard ADO.NET connection string parameters plus YDB-specific options.
+/// 
+/// For more information about YDB, see:
+/// <see href="https://ydb.tech/docs">YDB Documentation</see>.
 /// </remarks>
 public sealed class YdbConnectionStringBuilder : DbConnectionStringBuilder
 {

src/Ydb.Sdk/src/Ado/YdbDataSource.cs

@@ -2,34 +2,87 @@
 
 namespace Ydb.Sdk.Ado;
 
+/// <summary>
+/// Provides a simple way to create and configure a <see cref="YdbDataSource"/>.
+/// </summary>
+/// <remarks>
+/// YdbDataSourceBuilder provides a fluent interface for configuring connection strings
+/// and retry policies before building a YdbDataSource instance. It supports both
+/// string-based and strongly-typed connection string configuration.
+/// 
+/// For more information about YDB, see:
+/// <see href="https://ydb.tech/docs">YDB Documentation</see>.
+/// </remarks>
 public class YdbDataSourceBuilder
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="YdbDataSourceBuilder"/> class with default settings.
+    /// </summary>
+    /// <remarks>
+    /// Creates a new builder with default connection string and retry policy settings.
+    /// </remarks>
     public YdbDataSourceBuilder()
     {
         ConnectionStringBuilder = new YdbConnectionStringBuilder();
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="YdbDataSourceBuilder"/> class with the specified connection string.
+    /// </summary>
+    /// <param name="connectionString">The connection string to use for the data source.</param>
+    /// <remarks>
+    /// Creates a new builder with the specified connection string and default retry policy.
+    /// </remarks>
     public YdbDataSourceBuilder(string connectionString)
     {
         ConnectionStringBuilder = new YdbConnectionStringBuilder(connectionString);
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="YdbDataSourceBuilder"/> class with the specified connection string builder.
+    /// </summary>
+    /// <param name="connectionStringBuilder">The connection string builder to use for the data source.</param>
+    /// <remarks>
+    /// Creates a new builder with the specified connection string builder and default retry policy.
+    /// </remarks>
     public YdbDataSourceBuilder(YdbConnectionStringBuilder connectionStringBuilder)
     {
         ConnectionStringBuilder = connectionStringBuilder;
     }
 
     /// <summary>
-    /// A connection string builder that can be used to configure the connection string on the builder.
+    /// Gets the connection string builder that can be used to configure the connection string.
     /// </summary>
+    /// <remarks>
+    /// Provides strongly-typed properties for configuring YDB connection parameters.
+    /// Changes to this builder will be reflected in the built data source.
+    /// </remarks>
     public YdbConnectionStringBuilder ConnectionStringBuilder { get; }
 
     /// <summary>
-    /// Returns the connection string, as currently configured on the builder.
+    /// Gets the connection string as currently configured on the builder.
     /// </summary>
+    /// <remarks>
+    /// Returns the current connection string based on the configuration in the ConnectionStringBuilder.
+    /// </remarks>
     public string ConnectionString => ConnectionStringBuilder.ConnectionString;
 
+    /// <summary>
+    /// Gets or sets the retry policy for the data source.
+    /// </summary>
+    /// <remarks>
+    /// Specifies the retry policy to use for handling transient failures.
+    /// Default value is a YdbRetryPolicy with default configuration.
+    /// </remarks>
     public IRetryPolicy RetryPolicy { get; set; } = new YdbRetryPolicy(YdbRetryPolicyConfig.Default);
 
+    /// <summary>
+    /// Builds a new <see cref="YdbDataSource"/> instance with the current configuration.
+    /// </summary>
+    /// <returns>A new YdbDataSource instance configured with the current settings.</returns>
+    /// <remarks>
+    /// Creates a new data source with the configured connection string and retry policy.
+    /// The builder can be reused to create multiple data sources with different configurations.
+    /// </remarks>
     public YdbDataSource Build() => new(this);
 }

src/Ydb.Sdk/src/Ado/YdbDataSourceBuilder.cs

@@ -2,19 +2,78 @@
 
 namespace Ydb.Sdk.Ado;
 
+/// <summary>
+/// Represents a set of methods for creating instances of a provider's implementation of the data source classes.
+/// </summary>
+/// <remarks>
+/// YdbProviderFactory is the factory class for creating YDB-specific data source objects.
+/// It provides methods to create connections, commands, parameters, and other ADO.NET objects
+/// that are specific to the YDB database provider.
+/// 
+/// For more information about YDB, see:
+/// <see href="https://ydb.tech/docs">YDB Documentation</see>.
+/// </remarks>
 public class YdbProviderFactory : DbProviderFactory
 {
+    /// <summary>
+    /// Gets the singleton instance of the YdbProviderFactory.
+    /// </summary>
+    /// <remarks>
+    /// This static instance can be used to create YDB-specific ADO.NET objects
+    /// without instantiating the factory class directly.
+    /// </remarks>
     public static readonly YdbProviderFactory Instance = new();
 
+    /// <summary>
+    /// Returns a strongly typed <see cref="YdbCommand"/> object.
+    /// </summary>
+    /// <returns>A new instance of <see cref="YdbCommand"/>.</returns>
+    /// <remarks>
+    /// Creates a new YDB command object that can be used to execute SQL statements
+    /// and stored procedures against a YDB database.
+    /// </remarks>
     public override YdbCommand CreateCommand() => new();
 
+    /// <summary>
+    /// Returns a strongly typed <see cref="YdbConnection"/> object.
+    /// </summary>
+    /// <returns>A new instance of <see cref="YdbConnection"/>.</returns>
+    /// <remarks>
+    /// Creates a new YDB connection object that can be used to connect to a YDB database.
+    /// The connection must be opened before it can be used for database operations.
+    /// </remarks>
     public override YdbConnection CreateConnection() => new();
 
+    /// <summary>
+    /// Returns a strongly typed <see cref="YdbConnectionStringBuilder"/> object.
+    /// </summary>
+    /// <returns>A new instance of <see cref="YdbConnectionStringBuilder"/>.</returns>
+    /// <remarks>
+    /// Creates a new YDB connection string builder that provides strongly-typed properties
+    /// for building YDB connection strings with validation and IntelliSense support.
+    /// </remarks>
     public override YdbConnectionStringBuilder CreateConnectionStringBuilder() => new();
 
+    /// <summary>
+    /// Returns a strongly typed <see cref="YdbParameter"/> object.
+    /// </summary>
+    /// <returns>A new instance of <see cref="YdbParameter"/>.</returns>
+    /// <remarks>
+    /// Creates a new YDB parameter object that can be used to pass parameters
+    /// to YDB commands. The parameter supports YDB-specific data types and features.
+    /// </remarks>
     public override DbParameter CreateParameter() => new YdbParameter();
 
 #if NET7_0_OR_GREATER
+    /// <summary>
+    /// Returns a strongly typed <see cref="YdbDataSource"/> object.
+    /// </summary>
+    /// <param name="connectionString">The connection string to use for the data source.</param>
+    /// <returns>A new instance of <see cref="YdbDataSource"/> with the specified connection string.</returns>
+    /// <remarks>
+    /// Creates a new YDB data source object that provides a modern, lightweight way to work with YDB.
+    /// The data source is available only in .NET 7.0 and later versions.
+    /// </remarks>
     public override YdbDataSource CreateDataSource(string connectionString) => new();
 #endif
 }

src/Ydb.Sdk/src/Ado/YdbProviderFactory.cs

@@ -5,6 +5,17 @@
 
 namespace Ydb.Sdk.Ado;
 
+/// <summary>
+/// Represents a YDB transaction. This class cannot be inherited.
+/// </summary>
+/// <remarks>
+/// YdbTransaction represents a database transaction in YDB. It provides methods to commit or rollback
+/// changes made within the transaction. The transaction mode determines the isolation level and
+/// consistency guarantees.
+/// 
+/// For more information about YDB transactions, see:
+/// <see href="https://ydb.tech/docs/en/concepts/transactions">YDB Transactions Documentation</see>.
+/// </remarks>
 public sealed class YdbTransaction : DbTransaction
 {
     private readonly TransactionMode _transactionMode;
@@ -13,9 +24,32 @@ public sealed class YdbTransaction : DbTransaction
     private YdbConnection? _ydbConnection;
     private bool _isDisposed;
 
+    /// <summary>
+    /// Gets or sets the transaction identifier.
+    /// </summary>
+    /// <remarks>
+    /// The transaction ID is assigned by YDB when the transaction is started.
+    /// This property is used internally for transaction management.
+    /// </remarks>
     internal string? TxId { get; set; }
+
+    /// <summary>
+    /// Gets a value indicating whether the transaction has been completed.
+    /// </summary>
+    /// <remarks>
+    /// A transaction is considered completed when it has been committed, rolled back, or failed.
+    /// Once completed, the transaction cannot be used for further operations.
+    /// </remarks>
     internal bool Completed { get; private set; }
 
+    /// <summary>
+    /// Gets or sets a value indicating whether the transaction has failed.
+    /// </summary>
+    /// <remarks>
+    /// When true, indicates that the transaction has been rolled back by the server.
+    /// A failed transaction cannot be committed. The <see cref="Rollback"/> method
+    /// can be called to mark the transaction as completed.
+    /// </remarks>
     internal bool Failed
     {
         private get => _failed;
@@ -26,6 +60,13 @@ internal bool Failed
         }
     }
 
+    /// <summary>
+    /// Gets the transaction control for YDB operations.
+    /// </summary>
+    /// <remarks>
+    /// Returns null if the transaction is completed, otherwise returns the appropriate
+    /// transaction control based on whether the transaction has been started.
+    /// </remarks>
     internal TransactionControl? TransactionControl => Completed
         ? null
         : TxId == null
@@ -38,13 +79,65 @@ internal YdbTransaction(YdbConnection ydbConnection, TransactionMode transaction
         _transactionMode = transactionMode;
     }
 
+    /// <summary>
+    /// Commits the database transaction.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when the transaction has already been completed or the connection is closed.
+    /// </exception>
+    /// <exception cref="YdbOperationInProgressException">
+    /// Thrown when another operation is in progress on the connection.
+    /// </exception>
+    /// <exception cref="YdbException">
+    /// Thrown when the commit operation fails.
+    /// </exception>
     public override void Commit() => CommitAsync().GetAwaiter().GetResult();
 
+    /// <summary>
+    /// Asynchronously commits the database transaction.
+    /// </summary>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when the transaction has already been completed or the connection is closed.
+    /// </exception>
+    /// <exception cref="YdbOperationInProgressException">
+    /// Thrown when another operation is in progress on the connection.
+    /// </exception>
+    /// <exception cref="YdbException">
+    /// Thrown when the commit operation fails.
+    /// </exception>
     public override async Task CommitAsync(CancellationToken cancellationToken = new()) =>
         await FinishTransaction(txId => DbConnection!.Session.CommitTransaction(txId, cancellationToken));
 
+    /// <summary>
+    /// Rolls back the database transaction.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when the transaction has already been completed or the connection is closed.
+    /// </exception>
+    /// <exception cref="YdbOperationInProgressException">
+    /// Thrown when another operation is in progress on the connection.
+    /// </exception>
+    /// <exception cref="YdbException">
+    /// Thrown when the rollback operation fails.
+    /// </exception>
     public override void Rollback() => RollbackAsync().GetAwaiter().GetResult();
 
+    /// <summary>
+    /// Asynchronously rolls back the database transaction.
+    /// </summary>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when the transaction has already been completed or the connection is closed.
+    /// </exception>
+    /// <exception cref="YdbOperationInProgressException">
+    /// Thrown when another operation is in progress on the connection.
+    /// </exception>
+    /// <exception cref="YdbException">
+    /// Thrown when the rollback operation fails.
+    /// </exception>
     public override async Task RollbackAsync(CancellationToken cancellationToken = new())
     {
         if (Failed)
@@ -57,6 +150,13 @@ internal YdbTransaction(YdbConnection ydbConnection, TransactionMode transaction
         await FinishTransaction(txId => DbConnection!.Session.RollbackTransaction(txId, cancellationToken));
     }
 
+    /// <summary>
+    /// Gets the database connection associated with this transaction.
+    /// </summary>
+    /// <returns>The YdbConnection associated with this transaction, or null if disposed.</returns>
+    /// <exception cref="ObjectDisposedException">
+    /// Thrown when the transaction has been disposed.
+    /// </exception>
     protected override YdbConnection? DbConnection
     {
         get
@@ -66,6 +166,13 @@ protected override YdbConnection? DbConnection
         }
     }
 
+    /// <summary>
+    /// Gets the isolation level of this transaction.
+    /// </summary>
+    /// <remarks>
+    /// Returns Serializable for SerializableRw transaction mode, otherwise Unspecified.
+    /// The actual isolation level depends on the transaction mode used when creating the transaction.
+    /// </remarks>
     public override IsolationLevel IsolationLevel => _transactionMode == TransactionMode.SerializableRw
         ? IsolationLevel.Serializable
         : IsolationLevel.Unspecified;
@@ -107,6 +214,13 @@ private async Task FinishTransaction(Func<string, Task> finishMethod)
         }
     }
 
+    /// <summary>
+    /// Releases the unmanaged resources used by the YdbTransaction and optionally releases the managed resources.
+    /// </summary>
+    /// <param name="disposing">true to release both managed and unmanaged resources; false to release only unmanaged resources.</param>
+    /// <remarks>
+    /// If the transaction is not completed, it will be rolled back before disposal.
+    /// </remarks>
     protected override void Dispose(bool disposing)
     {
         if (_isDisposed || !disposing)
@@ -120,6 +234,13 @@ protected override void Dispose(bool disposing)
         _isDisposed = true;
     }
 
+    /// <summary>
+    /// Asynchronously releases the unmanaged resources used by the YdbTransaction.
+    /// </summary>
+    /// <returns>A ValueTask representing the asynchronous disposal operation.</returns>
+    /// <remarks>
+    /// If the transaction is not completed, it will be rolled back before disposal.
+    /// </remarks>
     public override async ValueTask DisposeAsync()
     {
         if (_isDisposed)