Update API docs

sdk/iot/Azure.Iot.Hub.Service/src/API Design.md

@@ -54,43 +54,43 @@ APIs for managing module identities, module twins, and querying modules
 public  class Modules
 {
     /// <summary>
-    /// Create a device module.
+    /// Create a device module identity.
     /// </summary>
     /// <param name="moduleIdentity">The module to create.</param>
     /// <param name="cancellationToken">The cancellation token.</param>
-    /// <returns></returns>
+    /// <returns>The newly created module identity</returns>
     public virtual async Task<Response<ModuleIdentity>> CreateIdentityAsync(ModuleIdentity moduleIdentity, CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Get a single device module.
+    /// Get a single device module identity.
     /// </summary>
     /// <param name="deviceId">The unique identifier of the device that contains the module.</param>
     /// <param name="moduleId">The unique identifier of the module to get.</param>
     /// <param name="cancellationToken">The cancellation token.</param>
-    /// <returns>The retrieved device.</returns>
+    /// <returns>The retrieved device module identity.</returns>
     public virtual async Task<Response<ModuleIdentity>> GetIdentityAsync(string deviceId, string moduleId, CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// List a set of device modules.
+    /// List a set of device's module identities.
     /// </summary>
     /// <param name="deviceId">The unique identifier of the device.</param>
     /// <param name="cancellationToken">The cancellation token.</param>
-    /// <returns>A pageable set of device modules.</returns>
-    public virtual async AsyncPageable<ModuleIdentity> GetIdentitiesAsync(string deviceId, CancellationToken cancellationToken = default);
+    /// <returns>A pageable set of device module identities.</returns>
+    public virtual async Task<Response<IReadOnlyList<ModuleIdentity>>> GetIdentitiesAsync(string deviceId, CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Update a device module.
+    /// Update a device module identity.
     /// </summary>
     /// <param name="moduleIdentity">The module to update.</param>
     /// <param name="ifMatch">A string representing a weak ETag for this module, as per RFC7232. The update operation is performed
     /// only if this ETag matches the value maintained by the server, indicating that the module has not been modified since it was last retrieved.
     /// The current ETag can be retrieved from the module identity last retrieved from the service. To force an unconditional update, set If-Match to the wildcard character (*).</param>
     /// <param name="cancellationToken">The cancellation token.</param>
-    /// <returns>The created or updated device module.</returns>
+    /// <returns>The updated device module identity.</returns>
     public virtual async Task<Response<ModuleIdentity>> UpdateIdentityAsync(ModuleIdentity moduleIdentity, string ifMatch = null, CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Delete a single device module.
+    /// Delete a single device module identity.
     /// </summary>
     /// <param name="deviceId">The unique identifier of the device that contains the module.</param>
     /// <param name="moduleId">The unique identifier of the module to get.</param>
@@ -102,7 +102,7 @@ public  class Modules
     public virtual async Task<Response> DeleteIdentityAsync(string deviceId, string moduleId, string ifMatch = null, CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Gets the module twin.
+    /// Gets the device module twin.
     /// </summary>
     /// <param name="deviceId">The unique identifier of the device.</param>
     /// <param name="moduleId">The unique identifier of the device module.</param>
@@ -111,7 +111,7 @@ public  class Modules
     public virtual async Task<Response<TwinData>> GetTwinAsync(string deviceId, string moduleId, CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// List a set of module twins.
+    /// List a set of device module twins.
     /// </summary>
     /// <param name="cancellationToken">The cancellation token.</param>
     /// <returns>A pageable set of module twins.</returns>