Skip to content

Commit

Permalink
Update service clients instantiation doc comments (Azure#2290)
Browse files Browse the repository at this point in the history 
* Update RegistryManager instantiation doc comments

* Update other service client doc comments.
  • Loading branch information
David R. Williamson authored Jan 27, 2022
1 parent 8212f32 commit 67428f7
Show file tree
Hide file tree
Showing 4 changed files with 110 additions and 61 deletions.
47 changes: 33 additions & 14 deletions iothub/service/src/DigitalTwin/DigitalTwinClient.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,10 @@ namespace Microsoft.Azure.Devices
{
/// <summary>
/// The Digital Twins Service Client contains methods to retrieve and update digital twin information, and invoke commands on a digital twin device.
/// For more information, see <see href="https://github.com/Azure/azure-iot-sdk-csharp#iot-hub-service-sdk"/>
/// </summary>
/// <remarks>
/// For more information, see <see href="https://github.com/Azure/azure-iot-sdk-csharp#iot-hub-service-sdk"/>
/// </remarks>
public class DigitalTwinClient : IDisposable
{
private const string HttpsEndpointPrefix = "https";
Expand All @@ -29,16 +31,20 @@ public class DigitalTwinClient : IDisposable

/// <summary>
/// Creates an instance of <see cref="DigitalTwinClient"/>, provided for unit testing purposes only.
/// Use the CreateFromConnectionString or Create method to create an instance to use the client.
/// </summary>
public DigitalTwinClient()
{
}

/// <summary>
/// Initializes a new instance of the <see cref="DigitalTwinClient"/> class.</summary>
/// Creates DigitalTwinClient from an IoT hub connection string.
/// </summary>
/// <param name="connectionString">The IoT hub's connection string.</param>
/// <param name="handlers">The delegating handlers to add to the http client pipeline. You can add handlers for tracing, implementing a retry strategy, routing requests through a proxy, etc.</param>
/// <param name="handlers">
/// The delegating handlers to add to the http client pipeline.
/// You can add handlers for tracing, implementing a retry strategy, routing requests through a proxy, etc.
/// </param>
/// <returns>A DigitalTwinsClient instance.</returns>
public static DigitalTwinClient CreateFromConnectionString(string connectionString, params DelegatingHandler[] handlers)
{
connectionString.ThrowIfNullOrWhiteSpace(nameof(connectionString));
Expand All @@ -49,15 +55,21 @@ public static DigitalTwinClient CreateFromConnectionString(string connectionStri
}

/// <summary>
/// Creates an instance of <see cref="DigitalTwinClient"/>.
/// Creates DigitalTwinClient, authenticating using an identity in Azure Active Directory (AAD).
/// </summary>
/// <param name="hostName">IoT hub host name.</param>
/// <param name="credential">Azure Active Directory credentials to authenticate with IoT hub. See <see cref="TokenCredential"/></param>
/// <param name="handlers">The delegating handlers to add to the http client pipeline. You can add handlers for tracing, implementing a retry strategy, routing requests through a proxy, etc.</param>
/// <returns>An instance of <see cref="DigitalTwinClient"/>.</returns>
/// <remarks>
/// For more information on configuring IoT hub with Azure Active Directory, see <see href="https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-dev-guide-azure-ad-rbac"/>
/// For more about information on the options of authenticating using a derived instance of <see cref="TokenCredential"/>, see
/// <see href="https://docs.microsoft.com/dotnet/api/overview/azure/identity-readme"/>.
/// For more information on configuring IoT hub with Azure Active Directory, see
/// <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-dev-guide-azure-ad-rbac"/>
/// </remarks>
/// <param name="hostName">IoT hub host name.</param>
/// <param name="credential">Azure Active Directory (AAD) credentials to authenticate with IoT hub. See <see cref="TokenCredential"/></param>
/// <param name="handlers">
/// The delegating handlers to add to the http client pipeline. You can add handlers for tracing,
/// implementing a retry strategy, routing requests through a proxy, etc.
/// </param>
/// <returns>A DigitalTwinsClient instance.</returns>
public static DigitalTwinClient Create(
string hostName,
TokenCredential credential,
Expand All @@ -78,12 +90,17 @@ public static DigitalTwinClient Create(
}

/// <summary>
/// Creates an instance of <see cref="DigitalTwinClient"/>.
/// Creates DigitalTwinClient using a shared access signature provided and refreshed as necessary by the caller.
/// </summary>
/// <remarks>
/// Users may wish to build their own shared access signature (SAS) tokens rather than give the shared key to the SDK and let it manage signing and renewal.
/// The <see cref="AzureSasCredential"/> object gives the SDK access to the SAS token, while the caller can update it as necessary using the
/// <see cref="AzureSasCredential.Update(string)"/> method.
/// </remarks>
/// <param name="hostName">IoT hub host name.</param>
/// <param name="credential">Credential that generates a SAS token to authenticate with IoT hub. See <see cref="AzureSasCredential"/>.</param>
/// <param name="handlers">The delegating handlers to add to the http client pipeline. You can add handlers for tracing, implementing a retry strategy, routing requests through a proxy, etc.</param>
/// <returns>An instance of <see cref="DigitalTwinClient"/>.</returns>
/// <returns>A DigitalTwinsClient instance.</returns>
public static DigitalTwinClient Create(
string hostName,
AzureSasCredential credential,
Expand Down Expand Up @@ -124,8 +141,10 @@ public virtual async Task<HttpOperationResponse<T, DigitalTwinGetHeaders>> GetDi

/// <summary>
/// Updates a digital twin.
/// <para>For further information on how to create the json-patch, see <see href="https://docs.microsoft.com/en-us/azure/iot-pnp/howto-manage-digital-twin"/></para>
/// </summary>
/// <remarks>
/// For further information on how to create the json-patch, see <see href="https://docs.microsoft.com/en-us/azure/iot-pnp/howto-manage-digital-twin"/>.
/// </remarks>
/// <param name="digitalTwinId">The Id of the digital twin.</param>
/// <param name="digitalTwinUpdateOperations">The application/json-patch+json operations to be performed on the specified digital twin.</param>
/// <param name="requestOptions">The optional settings for this request.</param>
Expand Down Expand Up @@ -183,7 +202,7 @@ public virtual async Task<HttpOperationResponse<DigitalTwinCommandResponse, Digi
/// <param name="payload">The command payload.</param>
/// <param name="requestOptions">The optional settings for this request.</param>
/// <param name="cancellationToken">The cancellationToken.</param>
/// <returns>The application/json command invocation response and the http response. </returns>
/// <returns>The application/json command invocation response and the http response.</returns>
public virtual async Task<HttpOperationResponse<DigitalTwinCommandResponse, DigitalTwinInvokeCommandHeaders>> InvokeComponentCommandAsync(
string digitalTwinId,
string componentName,
Expand Down
45 changes: 27 additions & 18 deletions iothub/service/src/JobClient/JobClient.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,9 @@ namespace Microsoft.Azure.Devices
/// <summary>
/// Job management
/// </summary>
/// <remarks>
/// For more information, see <see href="https://github.com/Azure/azure-iot-sdk-csharp#iot-hub-service-sdk"/>.
/// </remarks>
public class JobClient : IDisposable
{
private const string _jobsUriFormat = "/jobs/v2/{0}?{1}";
Expand All @@ -37,8 +40,7 @@ public class JobClient : IDisposable
private IHttpClientHelper _httpClientHelper;

/// <summary>
/// Creates an instance of <see cref="JobClient"/>, provided for unit testing purposes only.
/// Use the CreateFromConnectionString method to create an instance to use the client.
/// Creates JobClient, provided for unit testing purposes only.
/// </summary>
public JobClient()
{
Expand All @@ -62,22 +64,21 @@ internal JobClient(IotHubConnectionProperties connectionProperties, HttpTranspor
}

/// <summary>
/// Creates a JobClient from the IoT Hub connection string.
/// For more information, see <see href="https://github.com/Azure/azure-iot-sdk-csharp#iot-hub-service-sdk"/>
/// Creates JobClient from the IoT hub connection string.
/// </summary>
/// <param name="connectionString"> The IoT Hub connection string.</param>
/// <returns> A JobClient instance. </returns>
/// <param name="connectionString">The IoT hub connection string.</param>
/// <returns>A JobClient instance.</returns>
public static JobClient CreateFromConnectionString(string connectionString)
{
return CreateFromConnectionString(connectionString, new HttpTransportSettings());
}

/// <summary>
/// Creates a JobClient from the IoT Hub connection string and HTTP transport settings
/// Creates JobClient from the IoT hub connection string and HTTP transport settings.
/// </summary>
/// <param name="connectionString"> The IoT Hub connection string.</param>
/// <param name="transportSettings"> The HTTP transport settings.</param>
/// <returns> A JobClient instance. </returns>
/// <param name="connectionString">The IoT hub connection string.</param>
/// <param name="transportSettings">The HTTP transport settings.</param>
/// <returns>A JobClient instance.</returns>
public static JobClient CreateFromConnectionString(string connectionString, HttpTransportSettings transportSettings)
{
if (transportSettings == null)
Expand All @@ -93,15 +94,18 @@ public static JobClient CreateFromConnectionString(string connectionString, Http
#if !NET451

/// <summary>
/// Creates an instance of <see cref="JobClient"/>.
/// Creates JobClient, authenticating using an identity in Azure Active Directory (AAD).
/// </summary>
/// <param name="hostName">IoT hub host name.</param>
/// <param name="credential">Azure Active Directory credentials to authenticate with IoT hub. See <see cref="TokenCredential"/></param>
/// <param name="transportSettings">The HTTP transport settings.</param>
/// <returns>An instance of <see cref="JobClient"/>.</returns>
/// <remarks>
/// For more information on configuring IoT hub with Azure Active Directory, see <see href="https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-dev-guide-azure-ad-rbac"/>
/// For more about information on the options of authenticating using a derived instance of <see cref="TokenCredential"/>, see
/// <see href="https://docs.microsoft.com/dotnet/api/overview/azure/identity-readme"/>.
/// For more information on configuring IoT hub with Azure Active Directory, see
/// <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-dev-guide-azure-ad-rbac"/>
/// </remarks>
/// <param name="hostName">IoT hub host name.</param>
/// <param name="credential">Azure Active Directory (AAD) credentials to authenticate with IoT hub. See <see cref="TokenCredential"/></param>
/// <param name="transportSettings">The HTTP transport settings.</param>
/// <returns>A JobClient instance.</returns>
public static JobClient Create(
string hostName,
TokenCredential credential,
Expand All @@ -122,12 +126,17 @@ public static JobClient Create(
}

/// <summary>
/// Creates an instance of <see cref="JobClient"/>.
/// Creates JobClient using a shared access signature provided and refreshed as necessary by the caller.
/// </summary>
/// <remarks>
/// Users may wish to build their own shared access signature (SAS) tokens rather than give the shared key to the SDK and let it manage signing and renewal.
/// The <see cref="AzureSasCredential"/> object gives the SDK access to the SAS token, while the caller can update it as necessary using the
/// <see cref="AzureSasCredential.Update(string)"/> method.
/// </remarks>
/// <param name="hostName">IoT hub host name.</param>
/// <param name="credential">Credential that generates a SAS token to authenticate with IoT hub. See <see cref="AzureSasCredential"/>.</param>
/// <param name="transportSettings">The HTTP transport settings.</param>
/// <returns>An instance of <see cref="JobClient"/>.</returns>
/// <returns>A JobClient instance.</returns>
public static JobClient Create(
string hostName,
AzureSasCredential credential,
Expand Down
47 changes: 29 additions & 18 deletions iothub/service/src/RegistryManager.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
using Microsoft.Azure.Devices.Common.Exceptions;
using Microsoft.Azure.Devices.Shared;
using Newtonsoft.Json;
using System.Diagnostics.CodeAnalysis;

#if !NET451

Expand All @@ -26,9 +27,11 @@ namespace Microsoft.Azure.Devices
{
/// <summary>
/// Contains methods that services can use to perform create, remove, update and delete operations on devices.
/// For more information, see <see href="https://github.com/Azure/azure-iot-sdk-csharp#iot-hub-service-sdk"/>
/// </summary>
[System.Diagnostics.CodeAnalysis.SuppressMessage(
/// <remarks>
/// For more information, see <see href="https://github.com/Azure/azure-iot-sdk-csharp#iot-hub-service-sdk"/>
/// </remarks>
[SuppressMessage(
"Naming",
"CA1716:Identifiers should not match keywords",
Justification = "Cannot change parameter names as it is considered a breaking change.")]
Expand Down Expand Up @@ -70,8 +73,7 @@ public class RegistryManager : IDisposable
private IHttpClientHelper _httpClientHelper;

/// <summary>
/// Creates an instance of <see cref="RegistryManager"/>, provided for unit testing purposes only.
/// Use the CreateFromConnectionString method to create an instance to use the client.
/// Creates an instance of RegistryManager, provided for unit testing purposes only.
/// </summary>
public RegistryManager()
{
Expand All @@ -97,21 +99,22 @@ internal RegistryManager(string iotHubName, IHttpClientHelper httpClientHelper)
}

/// <summary>
/// Creates a RegistryManager from the IoT Hub connection string.
/// Creates RegistryManager from an IoT hub connection string.
/// </summary>
/// <param name="connectionString">The IoT Hub connection string.</param>
/// <returns>An RegistryManager instance.</returns>
/// <param name="connectionString">The IoT hub connection string.</param>
/// <returns>A RegistryManager instance.</returns>
public static RegistryManager CreateFromConnectionString(string connectionString)
{
return CreateFromConnectionString(connectionString, new HttpTransportSettings());
}

/// <summary>
/// Creates a RegistryManager from the IoT Hub connection string and transport settings
/// Creates an instance of RegistryManager, authenticating using an IoT hub connection string, and specifying
/// HTTP transport settings.
/// </summary>
/// <param name="connectionString">The IoT Hub connection string.</param>
/// <param name="connectionString">The IoT hub connection string.</param>
/// <param name="transportSettings">The HTTP transport settings.</param>
/// <returns>An RegistryManager instance.</returns>
/// <returns>A RegistryManager instance.</returns>
public static RegistryManager CreateFromConnectionString(string connectionString, HttpTransportSettings transportSettings)
{
if (transportSettings == null)
Expand All @@ -127,15 +130,18 @@ public static RegistryManager CreateFromConnectionString(string connectionString
#if !NET451

/// <summary>
/// Creates an instance of RegistryManager.
/// Creates RegistryManager, authenticating using an identity in Azure Active Directory (AAD).
/// </summary>
/// <param name="hostName">IoT hub host name.</param>
/// <param name="credential">Azure Active Directory credentials to authenticate with IoT hub. See <see cref="TokenCredential"/></param>
/// <param name="transportSettings">The HTTP transport settings.</param>
/// <returns>An instance of <see cref="RegistryManager"/>.</returns>
/// <remarks>
/// For more information on configuring IoT hub with Azure Active Directory, see <see href="https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-dev-guide-azure-ad-rbac"/>
/// For more about information on the options of authenticating using a derived instance of <see cref="TokenCredential"/>, see
/// <see href="https://docs.microsoft.com/dotnet/api/overview/azure/identity-readme"/>.
/// For more information on configuring IoT hub with Azure Active Directory, see
/// <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-dev-guide-azure-ad-rbac"/>
/// </remarks>
/// <param name="hostName">IoT hub host name.</param>
/// <param name="credential">Azure Active Directory (AAD) credentials to authenticate with IoT hub.</param>
/// <param name="transportSettings">The HTTP transport settings.</param>
/// <returns>A RegistryManager instance.</returns>
public static RegistryManager Create(
string hostName,
TokenCredential credential,
Expand All @@ -156,12 +162,17 @@ public static RegistryManager Create(
}

/// <summary>
/// Creates an instance of <see cref="RegistryManager"/>.
/// Creates RegistryManager using a shared access signature provided and refreshed as necessary by the caller.
/// </summary>
/// <remarks>
/// Users may wish to build their own shared access signature (SAS) tokens rather than give the shared key to the SDK and let it manage signing and renewal.
/// The <see cref="AzureSasCredential"/> object gives the SDK access to the SAS token, while the caller can update it as necessary using the
/// <see cref="AzureSasCredential.Update(string)"/> method.
/// </remarks>
/// <param name="hostName">IoT hub host name.</param>
/// <param name="credential">Credential that generates a SAS token to authenticate with IoT hub. See <see cref="AzureSasCredential"/>.</param>
/// <param name="transportSettings">The HTTP transport settings.</param>
/// <returns>An instance of <see cref="RegistryManager"/>.</returns>
/// <returns>A RegistryManager instance.</returns>
public static RegistryManager Create(
string hostName,
AzureSasCredential credential,
Expand Down
Loading

0 comments on commit 67428f7

Please sign in to comment.