docs: FIR-16886: added docstrings for all standard API methods (#79)

FireboltNETSDK/Client/FireboltCommand.cs

@@ -232,9 +232,9 @@ protected override Task<DbDataReader> ExecuteDbDataReaderAsync(CommandBehavior b
         }
 
         /// <summary>
-        /// Get query with ready parse parameters<b>null</b>.
+        /// Get query with ready parse parameters
         /// </summary>
-        /// <returns><b>null</b></returns>
+        /// <returns>Query with parameters ready to run.</returns>
         private string GetParamQuery(string commandText)
         {
             try
@@ -324,9 +324,9 @@ private string GetParamValue(object? value)
         }
 
         /// <summary>
-        /// Gets original data in JSON format for further manipulation<b>null</b>.
+        /// Gets original data in JSON format for further manipulation.
         /// </summary>
-        /// <returns><b>null</b></returns>
+        /// <returns>The data in JSON format</returns>
         private QueryResult? GetOriginalJsonData(string? Response)
         {
             if (Response == null) throw new FireboltException("Response is empty while GetOriginalJSONData");
@@ -359,27 +359,46 @@ public override UpdateRowSource UpdatedRowSource
             set => throw new NotImplementedException();
         }
 
+        /// <summary>
+        /// Gets or sets a value indicating whether the command object should be visible in a customized interface control.
+        /// </summary>
         public override bool DesignTimeVisible
         {
             get => _designTimeVisible;
             set => _designTimeVisible = value;
         }
 
+        /// <summary>
+        /// Executes the command that should retrieve data against the connection
+        /// </summary>
+        /// <param name="behavior"><see cref="CommandBehavior"/>ignored by the implementation</param>
+        /// <returns>Implementation of <see cref="DbDataReader"/></returns>
         protected override DbDataReader ExecuteDbDataReader(CommandBehavior behavior)
         {
             return CreateDbDataReader(Execute(StrictCommandText));
         }
 
+        /// <summary>
+        /// Creates DB parameter that can be used for query parameterization.
+        /// </summary>
+        /// <returns>Implementation of <see cref="DbParameterDbDataReader"/></returns>
         protected override DbParameter CreateDbParameter()
         {
             return new FireboltParameter();
         }
 
+        /// <summary>
+        /// Executes the command that does not retrieve data against the connection
+        /// </summary>
         public override int ExecuteNonQuery()
         {
             return ExecuteNonQueryAsync().GetAwaiter().GetResult();
         }
 
+        /// <summary>
+        /// Executes the query and returns the first column of the first row.
+        /// </summary>
+        /// <returns>The first column of the first row in the result set.</returns>
         public override object? ExecuteScalar()
         {
             using (DbDataReader reader = ExecuteReader())
@@ -401,11 +420,17 @@ public override int ExecuteNonQuery()
             return null;
         }
 
+        /// <summary>
+        /// Creates prepared (or compiled) version of command. Right now does nothing.
+        /// </summary>
         public override void Prepare()
         {
             // Empty implementation. Nothing to do here so far.
         }
 
+        /// <summary>
+        /// Asynchronous version of ExecuteNonQuery()
+        /// </summary>
         public override async Task<int> ExecuteNonQueryAsync(CancellationToken cancellationToken)
         {
             await ExecuteCommandAsync(StrictCommandText, cancellationToken);

FireboltNETSDK/Client/FireboltConnection.cs

@@ -22,9 +22,6 @@
 using FireboltDotNetSdk.Utils;
 using IsolationLevel = System.Data.IsolationLevel;
 using static FireboltDotNetSdk.Client.FireResponse;
-using static FireboltDotNetSdk.Client.FireboltCommand;
-using FireboltDotNetSdk.Exception;
-using System.Text;
 
 [assembly: InternalsVisibleTo("FireboltDotNetSdk.Tests")]
 [assembly: InternalsVisibleTo("FireboltDotNetSdk")]
@@ -137,6 +134,10 @@ internal int InfraVersion
         /// <returns>The state of the connection.</returns>
         public override ConnectionState State => _connectionState.State;
 
+        /// <summary>
+        /// Gets database version.
+        /// </summary>
+        /// <returns>The version of the database.</returns>
         public override string ServerVersion
         {
             get
@@ -149,8 +150,16 @@ public override string ServerVersion
             }
         }
 
+        /// <summary>
+        /// Gets the name of the database to which to connect.
+        /// </summary>
+        /// <returns>The name of the database to which to connect.</returns>
         public override string DataSource => _database;
 
+        /// <summary>
+        /// Connection string that holds all connection parameters as a semicolon separated key-value pairs.
+        /// </summary>
+        /// <returns>The connection staring</returns>
         [System.Diagnostics.CodeAnalysis.AllowNull]
         public override string ConnectionString
         {
@@ -370,6 +379,10 @@ public override void Open()
             OpenAsync().GetAwaiter().GetResult();
         }
 
+        /// <summary>
+        /// Simulates starting transaction. Due to transactions are not supported this method has not effect. 
+        /// </summary>
+        /// <returns>Simulated implementaion of <see cref="DbTransaction"/>.</returns>
         protected override DbTransaction BeginDbTransaction(IsolationLevel isolationLevel)
         {
             return new FireboltTransaction(this);

FireboltNETSDK/Client/FireboltConnectionStringBuilder.cs

@@ -185,6 +185,10 @@ private void InitVersion()
             Version = BuildSettings().Principal.Contains("@") ? 1 : 2;
         }
 
+        /// <summary>
+        /// Generates connection string from given parameters.
+        /// </summary>
+        /// <returns>The connection string</returns>
         public string ToConnectionString()
         {
             ICollection<string> x = (ICollection<string>)Keys;

FireboltNETSDK/Client/FireboltDataReader.cs

@@ -77,33 +77,44 @@ public FireboltDataReader(string? fullTableName, QueryResult queryResult, int de
             _depth = depth;
         }
 
+        /// <inheritdoc/>
         public override object this[string name] { get => GetValue(GetOrdinal(name)); }
 
+        /// <inheritdoc/>
         public override object this[int ordinal] { get => GetValue(ordinal); }
 
+        /// <inheritdoc/>
         public override bool IsClosed { get => _closed; }
 
+        /// <inheritdoc/>
         public override bool HasRows { get => _queryResult.Data.Count > 0; }
 
+        /// <inheritdoc/>
         public override int FieldCount { get => _queryResult.Meta.Count; }
 
+        /// <inheritdoc/>
         public override int Depth { get => _depth; }
 
+        /// <inheritdoc/>
         public override int RecordsAffected { get => 0; }
 
+        /// <inheritdoc/>
         public override int VisibleFieldCount { get => FieldCount; }
 
+        /// <inheritdoc/>
         public override void Close()
         {
             _closed = true;
         }
 
+        /// <inheritdoc/>
         public override Task CloseAsync()
         {
             Close();
             return Task.CompletedTask;
         }
 
+        /// <inheritdoc/>
         public override bool GetBoolean(int ordinal)
         {
             object value = GetValue(ordinal);
@@ -122,6 +133,7 @@ public override bool GetBoolean(int ordinal)
             }
         }
 
+        /// <inheritdoc/>
         public override byte GetByte(int ordinal)
         {
             object value = GetValue(ordinal);
@@ -139,6 +151,7 @@ public override byte GetByte(int ordinal)
             }
         }
 
+        /// <inheritdoc/>
         public override long GetBytes(int ordinal, long dataOffset, byte[]? buffer, int bufferOffset, int length)
         {
             object value = GetValue(ordinal);
@@ -152,6 +165,7 @@ public override long GetBytes(int ordinal, long dataOffset, byte[]? buffer, int
             return GetBuffer(bytes, dataOffset, buffer, bufferOffset, length);
         }
 
+        /// <inheritdoc/>
         public override char GetChar(int ordinal)
         {
             object value = GetValue(ordinal);
@@ -169,6 +183,7 @@ public override char GetChar(int ordinal)
             }
         }
 
+        /// <inheritdoc/>
         public override long GetChars(int ordinal, long dataOffset, char[]? buffer, int bufferOffset, int length)
         {
             return GetBuffer(GetString(ordinal).ToCharArray(), dataOffset, buffer, bufferOffset, length);
@@ -185,11 +200,13 @@ private long GetBuffer<T>(T[] source, long dataOffset, T[]? buffer, int bufferOf
             return limit;
         }
 
+        /// <inheritdoc/>
         public override string GetDataTypeName(int ordinal)
         {
             return _queryResult.Meta[ordinal].Type;
         }
 
+        /// <inheritdoc/>
         public override DateTime GetDateTime(int ordinal)
         {
             object value = GetValue(ordinal);
@@ -202,6 +219,7 @@ public override DateTime GetDateTime(int ordinal)
             }
         }
 
+        /// <inheritdoc/>
         public override decimal GetDecimal(int ordinal)
         {
             object value = GetValue(ordinal);
@@ -219,6 +237,7 @@ public override decimal GetDecimal(int ordinal)
             }
         }
 
+        /// <inheritdoc/>
         public override double GetDouble(int ordinal)
         {
             object value = GetValue(ordinal);
@@ -236,12 +255,14 @@ public override double GetDouble(int ordinal)
             }
         }
 
+        /// <inheritdoc/>
         //[EditorBrowsable(EditorBrowsableState.Never)]
         public override IEnumerator GetEnumerator()
         {
             return new DbEnumerator(this);
         }
 
+        /// <inheritdoc/>
         public override Type GetFieldType(int ordinal)
         {
             return GetTypeByName(GetDataTypeName(ordinal)) ?? throw new ArgumentNullException($"Cannot get type of column #{ordinal}");
@@ -297,6 +318,7 @@ private Type CreateArrayType(string elementTypeName, int dim)
             return type;
         }
 
+        /// <inheritdoc/>
         public override float GetFloat(int ordinal)
         {
             object value = GetValue(ordinal);
@@ -314,6 +336,13 @@ public override float GetFloat(int ordinal)
             }
         }
 
+        /// <summary>
+        /// Gets the value of the specified column as a globally unique identifier (GUID).
+        /// Due to Firebolt does not support GUID as a base type this function works only if the value is string that can be parsed as GUID.
+        /// Otherwise <exception cref="InvalidCastException">InvalidCastException</exception> is thrown. 
+        /// </summary>
+        /// <exception cref="FormatException">If format is invalid</exception>
+        /// <exception cref="OverflowException">If format is invalid</exception>
         public override Guid GetGuid(int ordinal)
         {
             object value = GetValue(ordinal);
@@ -324,6 +353,7 @@ public override Guid GetGuid(int ordinal)
             }
         }
 
+        /// <inheritdoc/>
         public override short GetInt16(int ordinal)
         {
             object value = ThrowIfInfinityOrNaN(GetValue(ordinal), typeof(short));
@@ -341,6 +371,7 @@ public override short GetInt16(int ordinal)
             }
         }
 
+        /// <inheritdoc/>
         public override int GetInt32(int ordinal)
         {
             object value = ThrowIfInfinityOrNaN(GetValue(ordinal), typeof(int));
@@ -357,6 +388,8 @@ public override int GetInt32(int ordinal)
                 default: throw new InvalidCastException($"Cannot cast ({value.GetType()}){value} to int");
             }
         }
+
+        /// <inheritdoc/>
         public override long GetInt64(int ordinal)
         {
             object value = ThrowIfInfinityOrNaN(GetValue(ordinal), typeof(long));
@@ -383,36 +416,43 @@ private static object ThrowIfInfinityOrNaN(object value, Type type)
             return value;
         }
 
+        /// <inheritdoc/>
         public override string GetName(int ordinal)
         {
             return _queryResult.Meta[ordinal].Name;
         }
 
+        /// <inheritdoc/>
         public override int GetOrdinal(string name)
         {
             return _queryResult?.Meta.FindIndex(m => m.Name == name) ?? throw new IndexOutOfRangeException($"Cannot find index for column {name}");
         }
 
+        /// <inheritdoc/>
         public override DataTable? GetSchemaTable()
         {
             return _fullTableName == null ? null : new DataTable(_fullTableName); // TODO split full table name that can contain schema_name.table_name (dot notation)
         }
 
+        /// <inheritdoc/>
         public override Task<DataTable?> GetSchemaTableAsync(CancellationToken cancellationToken = default)
         {
             return Task.FromResult(GetSchemaTable());
         }
 
         public override string GetString(int ordinal)
+        /// <inheritdoc/>
         {
             return GetValue(ordinal).ToString() ?? throw new InvalidOperationException($"String representation of column ${ordinal} is null");
         }
 
+        /// <inheritdoc/>
         public override object GetValue(int ordinal)
         {
             return GetValueSafely(ordinal) ?? throw new InvalidOperationException($"Column ${ordinal} is null");
         }
 
+        /// <inheritdoc/>
         public override int GetValues(object[] values)
         {
             List<object?> row = _queryResult.Data[_currentRowIndex] ?? new List<object?>();
@@ -428,6 +468,7 @@ public override int GetValues(object[] values)
             return n;
         }
 
+        /// <inheritdoc/>
         public override bool IsDBNull(int ordinal)
         {
             return GetValueSafely(ordinal) == DBNull.Value;
@@ -453,11 +494,16 @@ public override bool IsDBNull(int ordinal)
             return TypesConverter.ConvertToCSharpVal(value.ToString(), columnType);
         }
 
+        /// <summary>
+        /// Throws exception <exception cref="FireboltException">FireboltException</exception> because batch of read operations is not supported.
+        /// </summary>
+        /// <exception cref="FireboltException"></exception>
         public override bool NextResult()
         {
             throw new FireboltException("Batch operations are not supported");
         }
 
+        /// <inheritdoc/>
         public override bool Read()
         {
             int? max = (_queryResult?.Data?.Count ?? 0) - 1;