Add API reference documentation

And fix up some code doc comments

Milvus.Client.Tests/CollectionTests.cs

@@ -203,8 +203,7 @@ public async Task Load_Release()
             });
 
         await collection.CreateIndexAsync(
-            "float_vector", IndexType.Flat, SimilarityMetricType.L2,
-            new Dictionary<string, string>(), "float_vector_idx");
+            "float_vector", IndexType.Flat, SimilarityMetricType.L2, "float_vector_idx", new Dictionary<string, string>());
 
         await collection.LoadAsync();
         await collection.WaitForCollectionLoadAsync(
@@ -230,8 +229,7 @@ public async Task List()
             });
 
         await collection.CreateIndexAsync(
-            "float_vector", IndexType.Flat, SimilarityMetricType.L2,
-            new Dictionary<string, string>(), "float_vector_idx");
+            "float_vector", IndexType.Flat, SimilarityMetricType.L2, "float_vector_idx", new Dictionary<string, string>());
 
         Assert.Single(await Client.ListCollectionsAsync(), c => c.Name == CollectionName);
         Assert.DoesNotContain(await Client.ListCollectionsAsync(filter: CollectionFilter.InMemory),

Milvus.Client.Tests/DatabaseTests.cs

@@ -60,8 +60,7 @@ public async Task Search_on_non_default_database()
             });
 
         await collection.CreateIndexAsync(
-            "float_vector", IndexType.Flat, SimilarityMetricType.L2,
-            new Dictionary<string, string>(), "float_vector_idx");
+            "float_vector", IndexType.Flat, SimilarityMetricType.L2, "float_vector_idx", new Dictionary<string, string>());
 
         long[] ids = { 1, 2, 3, 4, 5 };
         string[] strings = { "one", "two", "three", "four", "five" };

Milvus.Client.Tests/IndexTests.cs

@@ -53,8 +53,9 @@ public async Task Create_scalar_index()
     [InlineData(IndexType.AutoIndex, """{ }""")]
     public async Task Index_types_float(IndexType indexType, string extraParamsString)
     {
-        await Collection.CreateIndexAsync("float_vector", indexType, SimilarityMetricType.L2,
-            JsonSerializer.Deserialize<Dictionary<string, string>>(extraParamsString));
+        await Collection.CreateIndexAsync(
+            "float_vector", indexType, SimilarityMetricType.L2,
+            extraParams: JsonSerializer.Deserialize<Dictionary<string, string>>(extraParamsString));
         await Collection.WaitForIndexBuildAsync("float_vector");
     }
 
@@ -73,8 +74,9 @@ await Client.CreateCollectionAsync(
                 FieldSchema.CreateBinaryVector("binary_vector", 8),
             });
 
-        await Collection.CreateIndexAsync("binary_vector", indexType, SimilarityMetricType.Jaccard,
-            JsonSerializer.Deserialize<Dictionary<string, string>>(extraParamsString));
+        await Collection.CreateIndexAsync(
+            "binary_vector", indexType, SimilarityMetricType.Jaccard,
+            extraParams: JsonSerializer.Deserialize<Dictionary<string, string>>(extraParamsString));
         await Collection.WaitForIndexBuildAsync("binary_vector");
     }
 
@@ -140,11 +142,10 @@ public async Task Describe()
 
         await Collection.CreateIndexAsync(
             "float_vector", IndexType.Flat, SimilarityMetricType.L2,
-            extraParams: new Dictionary<string, string>
+            indexName: "float_vector_idx", extraParams: new Dictionary<string, string>
             {
                 ["nlist"] = "1024"
-            },
-            indexName: "float_vector_idx");
+            });
         await Collection.WaitForIndexBuildAsync("float_vector");
 
         var indexes = await Collection.DescribeIndexAsync("float_vector");

Milvus.Client.Tests/PartitionTests.cs

@@ -34,8 +34,7 @@ public async Task Load_and_Release()
     {
         await Collection.CreatePartitionAsync("partition");
         await Collection.CreateIndexAsync(
-            "float_vector", IndexType.Flat, SimilarityMetricType.L2,
-            new Dictionary<string, string>(), "float_vector_idx");
+            "float_vector", IndexType.Flat, SimilarityMetricType.L2, "float_vector_idx", new Dictionary<string, string>());
         await Collection.WaitForIndexBuildAsync("float_vector");
 
         await Collection.LoadPartitionsAsync(new[] { "partition" });

Milvus.Client.Tests/SearchQueryTests.cs

@@ -247,8 +247,7 @@ await Client.CreateCollectionAsync(
 
         await binaryVectorCollection.CreateIndexAsync(
             "binary_vector", indexType, similarityMetricType,
-            new Dictionary<string, string>() { { "nlist", "128" } },
-            "float_vector_idx");
+            "float_vector_idx", new Dictionary<string, string>() { { "nlist", "128" } });
 
         long[] ids = { 1, 2, 3 };
         string[] strings = { "one", "two", "three" };
@@ -387,8 +386,7 @@ await TestEnvironment.Client.CreateCollectionAsync(
                 });
 
             await Collection.CreateIndexAsync(
-                "float_vector", IndexType.Flat, SimilarityMetricType.L2,
-                new Dictionary<string, string>(), "float_vector_idx");
+                "float_vector", IndexType.Flat, SimilarityMetricType.L2, "float_vector_idx", new Dictionary<string, string>());
 
             long[] ids = { 1, 2, 3, 4, 5 };
             string[] strings = { "one", "two", "three", "four", "five" };

Milvus.Client/MilvusClient.Database.cs

@@ -14,8 +14,7 @@ public partial class MilvusClient
     /// Available starting Milvus 2.2.9.
     /// </para>
     /// </remarks>
-    public async Task CreateDatabaseAsync(
-        string databaseName, CancellationToken cancellationToken = default)
+    public async Task CreateDatabaseAsync(string databaseName, CancellationToken cancellationToken = default)
     {
         Verify.NotNullOrWhiteSpace(databaseName);
 
@@ -32,6 +31,7 @@ await InvokeAsync(
     /// Available starting Milvus 2.2.9.
     /// </para>
     /// </remarks>
+    /// <returns>The list of available databases.</returns>
     public async Task<IReadOnlyList<string>> ListDatabasesAsync(CancellationToken cancellationToken = default)
     {
         ListDatabasesResponse response = await InvokeAsync(

Milvus.Client/MilvusClient.Role.cs

@@ -1,18 +1,19 @@
-using Google.Protobuf.Collections;
-
-namespace Milvus.Client;
+namespace Milvus.Client;
 
 public partial class MilvusClient
 {
     /// <summary>
-    /// Create a role.
+    /// Creates a role.
     /// </summary>
     /// <remarks>
     /// <para>
-    /// available in <c>Milvus 2.2.9</c>
+    /// For more details, see <see href="https://milvus.io/docs/rbac.md" />.
+    /// </para>
+    /// <para>
+    /// Roles are available starting Milvus 2.2.9.
     /// </para>
     /// </remarks>
-    /// <param name="roleName">Role name that will be created.</param>
+    /// <param name="roleName">The name of the role to be created.</param>
     /// <param name="cancellationToken">
     /// The token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None" />.
     /// </param>
@@ -27,18 +28,20 @@ public async Task CreateRoleAsync(string roleName, CancellationToken cancellatio
     }
 
     /// <summary>
-    /// Drop a role.
+    /// Drops a role.
     /// </summary>
     /// <remarks>
-    ///  <para>
-    /// available in <c>Milvus 2.2.9</c>
+    /// <para>
+    /// For more details, see <see href="https://milvus.io/docs/rbac.md" />.
+    /// </para>
+    /// <para>
+    /// Roles are available starting Milvus 2.2.9.
     /// </para>
     /// </remarks>
-    /// <param name="roleName"></param>
+    /// <param name="roleName">The name of the role to be dropped.</param>
     /// <param name="cancellationToken">
     /// The token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None" />.
     /// </param>
-    /// <returns></returns>
     public async Task DropRoleAsync(string roleName, CancellationToken cancellationToken = default)
     {
         Verify.NotNullOrWhiteSpace(roleName);
@@ -50,18 +53,18 @@ public async Task DropRoleAsync(string roleName, CancellationToken cancellationT
     }
 
     /// <summary>
-    /// Add user to role.
+    /// Adds a user to a role.
     /// </summary>
     /// <remarks>
-    ///<para>
-    /// The user will get permissions that the role are allowed to perform operations.
-    ///</para>
     /// <para>
-    /// available in <c>Milvus 2.2.9</c>
+    /// For more details, see <see href="https://milvus.io/docs/rbac.md" />.
+    /// </para>
+    /// <para>
+    /// Roles are available starting Milvus 2.2.9.
     /// </para>
     /// </remarks>
-    /// <param name="username">Username.</param>
-    /// <param name="roleName">Role name.</param>
+    /// <param name="username">The name of the username to be added to the role.</param>
+    /// <param name="roleName">The name of the role the user will be added to.</param>
     /// <param name="cancellationToken">
     /// The token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None" />.
     /// </param>
@@ -83,18 +86,18 @@ public async Task AddUserToRoleAsync(
     }
 
     /// <summary>
-    /// Remove user from role.
+    /// Removes a user from a role.
     /// </summary>
     /// <remarks>
     /// <para>
-    /// The user will remove permissions that the role are allowed to perform operations.
+    /// For more details, see <see href="https://milvus.io/docs/rbac.md" />.
     /// </para>
     /// <para>
-    /// available in <c>Milvus 2.2.9</c>
+    /// Roles are available starting Milvus 2.2.9.
     /// </para>
     /// </remarks>
-    /// <param name="username">Username.</param>
-    /// <param name="roleName">RoleName.</param>
+    /// <param name="username">The name of the user to be removed from the role.</param>
+    /// <param name="roleName">The name of the role from which the user is to be removed.</param>
     /// <param name="cancellationToken">
     /// The token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None" />.
     /// </param>
@@ -130,6 +133,10 @@ public async Task RemoveUserFromRoleAsync(
     /// Roles are available starting Milvus 2.2.9.
     /// </para>
     /// </remarks>
+    /// <returns>
+    /// A <see cref="RoleResult" /> instance containing information about the role, or <c>null</c> if the role does not
+    /// exist.
+    /// </returns>
     public async Task<RoleResult?> SelectRoleAsync(
         string roleName,
         bool includeUserInfo = true,
@@ -179,6 +186,7 @@ await InvokeAsync(GrpcClient.SelectRoleAsync, request, static r => r.Status, can
     /// Roles are available starting Milvus 2.2.9.
     /// </para>
     /// </remarks>
+    /// <returns>A list of <see cref="RoleResult" /> instances containing information about all the roles.</returns>
     public async Task<IReadOnlyList<RoleResult>> SelectAllRolesAsync(
         bool includeUserInfo = true,
         CancellationToken cancellationToken = default)
@@ -213,6 +221,10 @@ await InvokeAsync(GrpcClient.SelectRoleAsync, request, static r => r.Status, can
     /// Roles are available starting Milvus 2.2.9.
     /// </para>
     /// </remarks>
+    /// <returns>
+    /// A <see cref="UserResult" /> instance containing information about the user, or <c>null</c> if the user does not
+    /// exist.
+    /// </returns>
     public async Task<UserResult?> SelectUserAsync(
         string username,
         bool includeRoleInfo = true,
@@ -262,6 +274,7 @@ await InvokeAsync(GrpcClient.SelectUserAsync, request, static r => r.Status, can
     /// Roles are available starting Milvus 2.2.9.
     /// </para>
     /// </remarks>
+    /// <returns>A list of <see cref="UserResult" /> instances containing information about all the users.</returns>
     public async Task<IReadOnlyList<UserResult>> SelectAllUsersAsync(
         bool includeRoleInfo = true,
         CancellationToken cancellationToken = default)
@@ -331,7 +344,6 @@ public async Task GrantRolePrivilegeAsync(
 
     /// <summary>
     /// Revokes a privilege from a role.
-    /// <see href="https://milvus.io/docs/users_and_roles.md"/>
     /// </summary>
     /// <param name="roleName">The name of the role to be revoked a privilege.</param>
     /// <param name="object">
@@ -380,16 +392,21 @@ public async Task RevokeRolePrivilegeAsync(
     }
 
     /// <summary>
-    ///  List a grant info for the role and the specific object
+    /// Lists a grant info for the role and the specific object.
     /// </summary>
+    /// <param name="roleName">The name of the role.</param>
+    /// <param name="cancellationToken">
+    /// The token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None" />.
+    /// </param>
     /// <remarks>
     /// <para>
-    /// available in <c>Milvus 2.2.9</c>
+    /// For more details, see <see href="https://milvus.io/docs/rbac.md" />.
+    /// </para>
+    /// <para>
+    /// Roles are available starting Milvus 2.2.9.
     /// </para>
     /// </remarks>
-    /// <param name="roleName">Role name. RoleName cannot be empty or null.</param>
-    /// <param name="cancellationToken">Cancellation name.</param>
-    /// <returns></returns>
+    /// <returns>A list of <see cref="GrantEntity" /> instances describing the grants assigned to the role.</returns>
     public async Task<IReadOnlyList<GrantEntity>> ListGrantsForRoleAsync(
         string roleName,
         CancellationToken cancellationToken = default)

Milvus.Client/MilvusCollection.Collection.cs

@@ -12,6 +12,7 @@ public partial class MilvusCollection
     /// <param name="cancellationToken">
     /// The token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None" />.
     /// </param>
+    /// <returns>A description of the collection.</returns>
     public async Task<MilvusCollectionDescription> DescribeAsync(CancellationToken cancellationToken = default)
     {
         var request = new DescribeCollectionRequest { CollectionName = Name };
@@ -110,6 +111,7 @@ await _client.InvokeAsync(_client.GrpcClient.DropCollectionAsync, request, cance
     /// <param name="cancellationToken">
     /// The token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None" />.
     /// </param>
+    /// <returns>The number of entities currently in the collection.</returns>
     public async Task<int> GetEntityCountAsync(CancellationToken cancellationToken = default)
     {
         var request = new GetCollectionStatisticsRequest { CollectionName = Name };
@@ -149,7 +151,7 @@ await _client.InvokeAsync(_client.GrpcClient.LoadCollectionAsync, request, cance
     }
 
     /// <summary>
-    /// Release a collection loaded before
+    /// Releases a collection that has been previously loaded.
     /// </summary>
     /// <param name="cancellationToken">Cancellation token</param>
     public async Task ReleaseAsync(CancellationToken cancellationToken = default)
@@ -169,6 +171,7 @@ await _client.InvokeAsync(_client.GrpcClient.ReleaseCollectionAsync, request, ca
     /// <param name="cancellationToken">
     /// The token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None" />.
     /// </param>
+    /// <returns>The loading progress of the collection.</returns>
     public async Task<long> GetLoadingProgressAsync(
         IReadOnlyList<string>? partitionNames = null,
         CancellationToken cancellationToken = default)
@@ -192,7 +195,9 @@ await _client.InvokeAsync(_client.GrpcClient.GetLoadingProgressAsync, request, s
     /// Polls Milvus for loading progress of a collection until it is fully loaded.
     /// To perform a single progress check, use <see cref="GetLoadingProgressAsync" />.
     /// </summary>
-    /// <param name="partitionNames">Partition names.</param>
+    /// <param name="partitionNames">
+    /// An optional list of partition names for which to check the loading progress.
+    /// </param>
     /// <param name="waitingInterval">Waiting interval. Defaults to 500 milliseconds.</param>
     /// <param name="timeout">How long to poll for before throwing a <see cref="TimeoutException" />.</param>
     /// <param name="progress">Provides information about the progress of the loading operation.</param>
@@ -220,11 +225,12 @@ await Utils.Poll(
     }
 
     /// <summary>
-    /// Returns the loading progress for a collection, and optionally one or more of its partitions.
+    /// Compacts the collection.
     /// </summary>
     /// <param name="cancellationToken">
     /// The token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None" />.
     /// </param>
+    /// <returns>The compaction ID.</returns>
     public async Task<long> CompactAsync(CancellationToken cancellationToken = default)
     {
         MilvusCollectionDescription description = await DescribeAsync(cancellationToken).ConfigureAwait(false);

Milvus.Client/MilvusCollection.Entity.cs

@@ -55,10 +55,11 @@ await _client.InvokeAsync(_client.GrpcClient.InsertAsync, request, static r => r
     /// Deletes rows from a collection by given expression.
     /// </summary>
     /// <param name="expression">A boolean expression determining which rows are to be deleted.</param>
-    /// <param name="partitionName">An optional name of a partition from which rows are to be deleted..</param>
+    /// <param name="partitionName">An optional name of a partition from which rows are to be deleted.</param>
     /// <param name="cancellationToken">
     /// The token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None" />.
     /// </param>
+    /// <returns>A <see cref="MutationResult" /> containing information about the drop operation.</returns>
     public async Task<MutationResult> DeleteAsync(
         string expression,
         string? partitionName = null,
@@ -299,6 +300,7 @@ static void PopulateBinaryVectorData(
     /// <param name="cancellationToken">
     /// The token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None" />.
     /// </param>
+    /// <returns>A <see cref="FlushResult" /> containing information about the flush operation.</returns>
     public Task<FlushResult> FlushAsync(CancellationToken cancellationToken = default)
         => _client.FlushAsync(new[] { Name }, cancellationToken);
 
@@ -325,13 +327,14 @@ public async Task<IReadOnlyList<PersistentSegmentInfo>> GetPersistentSegmentInfo
     }
 
     /// <summary>
-    /// Retrieves rows from a collection via scalar filtering based on a boolean expression
+    /// Retrieves rows from a collection via scalar filtering based on a boolean expression.
     /// </summary>
     /// <param name="expression">A boolean expression determining which rows are to be returned.</param>
     /// <param name="parameters">Various additional optional parameters to configure the query.</param>
     /// <param name="cancellationToken">
     /// The token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None" />.
     /// </param>
+    /// <returns>A list of <see cref="FieldData{TData}" /> instances with the query results.</returns>
     public async Task<IReadOnlyList<FieldData>> QueryAsync(
         string expression,
         QueryParameters? parameters = null,