updates

Author: KirillKurdyukov

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

@@ -8,15 +8,19 @@ namespace Ydb.Sdk.Ado;
 /// <remarks>
 /// TransactionMode defines the isolation level and consistency guarantees
 /// 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>
 /// </remarks>
 public enum TransactionMode
 {
     /// <summary>
     /// Serializable read-write transaction mode.
     /// </summary>
     /// <remarks>
-    /// Provides the highest isolation level with full ACID guarantees.
-    /// All reads and writes are serializable, ensuring complete consistency.
+    /// Provides the strictest isolation level for custom transactions.
+    /// Guarantees that the result of successful parallel transactions is equivalent
+    /// to their serial execution, with no read anomalies for successful transactions.
     /// This is the default mode for read-write operations.
     /// </remarks>
     SerializableRw,
@@ -25,8 +29,9 @@ public enum TransactionMode
     /// Snapshot read-only transaction mode.
     /// </summary>
     /// <remarks>
-    /// Provides a consistent snapshot of the database at a specific point in time.
-    /// All reads within the transaction see the same consistent state.
+    /// All read operations within the transaction access the database snapshot.
+    /// All data reads are consistent. The snapshot is taken when the transaction begins,
+    /// meaning the transaction sees all changes committed before it began.
     /// Only read operations are allowed.
     /// </remarks>
     SnapshotRo,
@@ -35,8 +40,9 @@ public enum TransactionMode
     /// Stale read-only transaction mode.
     /// </summary>
     /// <remarks>
-    /// Allows reading potentially stale data for better performance.
-    /// Provides eventual consistency guarantees but may return outdated information.
+    /// Read operations within the transaction may return results that are slightly
+    /// out-of-date (lagging by fractions of a second). Each individual read returns
+    /// consistent data, but no consistency between different reads is guaranteed.
     /// Only read operations are allowed.
     /// </remarks>
     StaleRo,
@@ -45,8 +51,10 @@ public enum TransactionMode
     /// Online read-only transaction mode.
     /// </summary>
     /// <remarks>
-    /// Provides real-time read access with strong consistency.
-    /// Reads the most recent committed data without allowing inconsistent reads.
+    /// Each read operation in the transaction reads the data that is most recent
+    /// at execution time. Each individual read operation returns consistent data,
+    /// but no consistency is guaranteed between reads. Reading the same table range
+    /// twice may return different results.
     /// Only read operations are allowed.
     /// </remarks>
     OnlineRo,
@@ -55,8 +63,10 @@ public enum TransactionMode
     /// Online inconsistent read-only transaction mode.
     /// </summary>
     /// <remarks>
-    /// Provides real-time read access but allows inconsistent reads for better performance.
-    /// May return data from different points in time within the same transaction.
+    /// Each read operation in the transaction reads the data that is most recent
+    /// at execution time. Even the data fetched by a particular read operation may
+    /// contain inconsistent results. This mode provides the highest performance
+    /// but the lowest consistency guarantees.
     /// Only read operations are allowed.
     /// </remarks>
     OnlineInconsistentRo

src/Ydb.Sdk/src/Ado/YdbType/YdbDbType.cs

@@ -3,10 +3,25 @@
 namespace Ydb.Sdk.Ado.YdbType;
 
 /// <summary>
-/// See <a href="https://ydb.tech/docs/en/yql/reference/types/primitive">YDB Primitive Types</a> for details.
+/// Specifies the data type of the <see cref="YdbParameter"/>.
 /// </summary>
+/// <remarks>
+/// YdbDbType represents the primitive data types supported by YDB.
+/// 
+/// For more information about YDB primitive types, see:
+/// <see href="https://ydb.tech/docs/en/yql/reference/types/primitive">YDB Primitive Types Documentation</see>
+/// </remarks>
 public enum YdbDbType
 {
+    /// <summary>
+    /// Unspecified data type.
+    /// </summary>
+    /// <remarks>
+    /// When this type is used, the <see cref="YdbParameter"/> tries to automatically determine
+    /// the appropriate YDB data type based on the system type of the parameter value.
+    /// This provides convenience, but it may not always match the intended YDB type and
+    /// doesn't support null values.
+    /// </remarks>
     Unspecified,
 
     /// <summary>
@@ -79,13 +94,13 @@ public enum YdbDbType
     Double,
 
     /// <summary>
-    /// A real number with the specified precision, 16 bytes in size.
-    /// Precision is the maximum total number of decimal digits stored and can range from 1 to 35.
-    /// Scale is the maximum number of decimal digits stored
-    /// to the right of the decimal point and can range from 0 to the precision value.
+    /// Represents a fixed-point real number type with user-specified precision and scale, stored in 16 bytes.
+    /// Precision is the maximum total number of decimal digits stored (1 to 35).
+    /// Scale is the number of decimal digits to the right of the decimal point (0 to the precision value).
     /// </summary>
     /// <remarks>
-    /// Precision and Scale are specified in the <see cref="Ydb.Sdk.Ado.YdbParameter"/>.
+    /// Precision and Scale must be specified in <see cref="Ydb.Sdk.Ado.YdbParameter"/>.
+    /// If not specified, the default values (precision: 22, scale: 9) are used.
     /// </remarks>
     Decimal,
 
@@ -164,16 +179,44 @@ public enum YdbDbType
     /// </summary>
     /// <remarks>
     /// Value range: From -136 years to +136 years. Internal representation: Signed 64-bit integer.
-    /// Can't be used in the primary key.
     /// </remarks>
     Interval,
 
+    /// <summary>
+    /// Date with extended range, precision to the day.
+    /// </summary>
+    /// <remarks>
+    /// Extended range date type that supports dates before 01.01.1970 and beyond the standard Date range.
+    /// Provides better support for historical dates and future dates.
+    /// </remarks>
     Date32,
 
+    /// <summary>
+    /// Date/time with extended range, precision to the second.
+    /// </summary>
+    /// <remarks>
+    /// Extended range datetime type that supports date/time values before 01.01.1970 and
+    /// beyond the standard Datetime range.
+    /// Provides better support for historical timestamps and future timestamps.
+    /// </remarks>
     Datetime64,
 
+    /// <summary>
+    /// Date/time with extended range, precision to the microsecond.
+    /// </summary>
+    /// <remarks>
+    /// Extended range timestamp type that supports microsecond-precision timestamps
+    /// before 01.01.1970 and beyond the standard Timestamp range. Provides better support for historical and future timestamps.
+    /// </remarks>
     Timestamp64,
 
+    /// <summary>
+    /// Time interval with extended range, precision to microseconds.
+    /// </summary>
+    /// <remarks>
+    /// Extended range interval type that supports larger time intervals
+    /// beyond the standard Interval range.
+    /// </remarks>
     Interval64
 }