Documentation feedback (#20)

Co-authored-by: Stephen Hewitt <[email protected]>
Co-authored-by: jeffrey-elliott <[email protected]>
Co-authored-by: Steve Hewitt <[email protected]>
Co-authored-by: Aaron Morton <[email protected]>

Author: 4 people

src/DataStax.AstraDB.DataApi/Core/Commands/Command.cs

@@ -326,7 +326,7 @@ private async Task<T> RunCommandAsync<T>(HttpMethod method, bool runSynchronousl
                         responseContent = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
                         MaybeLogDebugMessage("Response Status Code: {StatusCode}", response.StatusCode);
                         MaybeLogDebugMessage("Content: {Content}", responseContent);
-                        throw new HttpRequestException($"Request to failed with status code {response.StatusCode}.");
+                        throw new HttpRequestException($"Request failed with status code {response.StatusCode}.");
                     }
                 }
                 responseContent = await response.Content.ReadAsStringAsync().ConfigureAwait(false);

src/DataStax.AstraDB.DataApi/Core/Database.cs

@@ -905,7 +905,7 @@ private async Task<IEnumerable<TableInfo>> ListTablesAsync(DatabaseCommandOption
     /// Synchronous version of <see cref="ListTableNamesAsync()"/>
     /// </summary>
     /// <returns></returns>
-    public IEnumerable<string> ListTableNames()
+    public List<string> ListTableNames()
     {
         return ListTableNames(null);
     }
@@ -915,7 +915,7 @@ public IEnumerable<string> ListTableNames()
     /// </summary>
     /// <param name="options">The options to use for the command, useful for overriding the keyspace, for example.</param>
     /// <returns></returns>
-    public IEnumerable<string> ListTableNames(DatabaseCommandOptions options)
+    public List<string> ListTableNames(DatabaseCommandOptions options)
     {
         return ListTableNamesAsync(options, true, true).ResultSync();
     }
@@ -924,7 +924,7 @@ public IEnumerable<string> ListTableNames(DatabaseCommandOptions options)
     /// List the tables in the database.
     /// </summary>
     /// <returns></returns>
-    public Task<IEnumerable<string>> ListTableNamesAsync()
+    public Task<List<string>> ListTableNamesAsync()
     {
         return ListTableNamesAsync(null);
     }
@@ -934,12 +934,12 @@ public Task<IEnumerable<string>> ListTableNamesAsync()
     /// </summary>
     /// <param name="options">The options to use for the command, useful for overriding the keyspace, for example.</param>
     /// <returns></returns>
-    public Task<IEnumerable<string>> ListTableNamesAsync(DatabaseCommandOptions options)
+    public Task<List<string>> ListTableNamesAsync(DatabaseCommandOptions options)
     {
         return ListTableNamesAsync(options, true, false);
     }
 
-    private async Task<IEnumerable<string>> ListTableNamesAsync(DatabaseCommandOptions options, bool includeDetails, bool runSynchronously)
+    private async Task<List<string>> ListTableNamesAsync(DatabaseCommandOptions options, bool includeDetails, bool runSynchronously)
     {
         var payload = new
         {

src/DataStax.AstraDB.DataApi/Core/Query/DocumentFindOptions.cs

@@ -20,6 +20,10 @@ namespace DataStax.AstraDB.DataApi.Core.Query;
 
 public class DocumentFindOptions<T> : FindOptions<T, DocumentSortBuilder<T>>
 {
+    /// <summary>
+    /// The sort to apply when running the query.
+    /// </summary>
     [JsonIgnore]
     public override DocumentSortBuilder<T> Sort { get; set; }
+
 }

src/DataStax.AstraDB.DataApi/Core/Query/FindOptions.cs

@@ -25,7 +25,11 @@ public abstract class FindOptions<T, TSort> : IFindOptions<T, TSort> where TSort
     [JsonIgnore]
     public IProjectionBuilder Projection { get; set; }
 
-    internal bool? IncludeSimilarity { get; set; }
+    /// <summary>
+    /// Whether to include a similarity score in the results or not (when performing a vector sort).
+    /// </summary>
+    [JsonIgnore]
+    public bool? IncludeSimilarity { get; set; }
 
     protected bool? _includeSortVector;
 

src/DataStax.AstraDB.DataApi/Core/Results/ListTableNamesResult.cs

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+using System.Collections.Generic;
 using System.Text.Json.Serialization;
 
 namespace DataStax.AstraDB.DataApi.Core.Results;
@@ -24,8 +25,8 @@ namespace DataStax.AstraDB.DataApi.Core.Results;
 public class ListTableNamesResult
 {
     /// <summary>
-    /// An array of table names.
+    /// The list of table names.
     /// </summary>
     [JsonPropertyName("tables")]
-    public string[] Tables { get; set; }
+    public List<string> Tables { get; set; }
 }

src/DataStax.AstraDB.DataApi/Core/TableDeleteOptions.cs

@@ -0,0 +1,35 @@
+/*
+ * Copyright DataStax, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+using DataStax.AstraDB.DataApi.Core.Query;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text.Json.Serialization;
+
+namespace DataStax.AstraDB.DataApi.Core;
+
+/// <summary>
+/// Options for deleting a row from a table
+/// </summary>
+/// <typeparam name="T"></typeparam>
+public class TableDeleteOptions<T> where T : class
+{
+  internal Filter<T> Filter { get; set; }
+
+  [JsonInclude]
+  [JsonPropertyName("filter")]
+  internal Dictionary<string, object> FilterMap => Filter == null ? new Dictionary<string, object>() : Filter.Serialize();
+}

src/DataStax.AstraDB.DataApi/DataStax.AstraDB.DataApi.csproj

@@ -18,6 +18,7 @@
     <PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
     <PackageIcon>packageIcon.png</PackageIcon>
     <PackageReadmeFile>README.md</PackageReadmeFile>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
   <ItemGroup>

src/DataStax.AstraDB.DataApi/SerDes/TableInsertManyResultConverter.cs

@@ -14,24 +14,33 @@
  * limitations under the License.
  */
 
+using DataStax.AstraDB.DataApi.Core.Results;
+using DataStax.AstraDB.DataApi.Tables;
 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Text.Json;
 using System.Text.Json.Serialization;
-using DataStax.AstraDB.DataApi.Core.Results;
-using DataStax.AstraDB.DataApi.Tables;
 
 namespace DataStax.AstraDB.DataApi.SerDes;
 
-public class TableInsertManyResultConverter : JsonConverter<TableInsertManyResult>
+internal class TableInsertOneResultConverter : TableInsertResultConverter<TableInsertOneResult>
 {
-    public override TableInsertManyResult Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+}
+
+internal class TableInsertManyResultConverter : TableInsertResultConverter<TableInsertManyResult>
+{
+}
+
+internal class TableInsertResultConverter<T> : JsonConverter<T> where T : TableInsertManyResult, new()
+{
+
+    public override T Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
     {
         if (reader.TokenType != JsonTokenType.StartObject)
             throw new JsonException("Expected StartObject token");
 
-        var result = new TableInsertManyResult();
+        var result = new T();
         JsonDocument insertedIdsDoc = null;
         JsonDocument documentResponsesDoc = null;
 
@@ -207,7 +216,7 @@ private object DeserializeValue(JsonElement element, PrimaryKeySchema schema, Js
         }
     }
 
-    public override void Write(Utf8JsonWriter writer, TableInsertManyResult value, JsonSerializerOptions options)
+    public override void Write(Utf8JsonWriter writer, T value, JsonSerializerOptions options)
     {
         throw new NotSupportedException("Serialization is not implemented for TableInsertManyResult");
     }