[RS Backup] Fixing 7349803 (documentation fixes) in Service Client Adapter Layer

Author: dragonfly91

src/ResourceManager/RecoveryServices.Backup/Commands.RecoveryServices.Backup.ServiceClientAdapter/BMSAPIs/ContainerAPIs.cs

@@ -27,8 +27,8 @@ public partial class ServiceClientAdapter
         /// <summary>
         /// Fetches protection containers in the vault according to the query params
         /// </summary>
-        /// <param name="parameters"></param>
-        /// <returns></returns>
+        /// <param name="parameters">Query parameters</param>
+        /// <returns>List of protection containers</returns>
         public IEnumerable<ProtectionContainerResource> ListContainers(
             ProtectionContainerListQueryParams queryParams)
         {
@@ -42,10 +42,10 @@ public IEnumerable<ProtectionContainerResource> ListContainers(
         }
 
         /// <summary>
-        /// Fetches backup engine in the vault according to the query params
+        /// Fetches backup engines in the vault according to the query params
         /// </summary>
-        /// <param name="parameters"></param>
-        /// <returns></returns>
+        /// <param name="parameters">Query parameters</param>
+        /// <returns>List of backup engines</returns>
         public IEnumerable<BackupEngineResource> ListBackupEngines(BackupEngineListQueryParams queryParams)
         {
             PaginationRequest paginationParam = new PaginationRequest();
@@ -63,7 +63,7 @@ public IEnumerable<BackupEngineResource> ListBackupEngines(BackupEngineListQuery
         /// <summary>
         /// Triggers refresh of container catalog in service
         /// </summary>
-        /// <returns></returns>
+        /// <returns>Response of the job created in the service</returns>
         public BaseRecoveryServicesJobResponse RefreshContainers()
         {
             string resourceName = BmsAdapter.GetResourceName();
@@ -78,9 +78,8 @@ public BaseRecoveryServicesJobResponse RefreshContainers()
         }
 
         /// <summary>
-        /// Unregister a container in service
+        /// Triggers unregister of a container in service
         /// </summary>
-        /// <returns></returns>
         public AzureOperationResponse UnregisterContainers(string containerName)
         {
             string resourceName = BmsAdapter.GetResourceName();

src/ResourceManager/RecoveryServices.Backup/Commands.RecoveryServices.Backup.ServiceClientAdapter/BMSAPIs/ItemAPIs.cs

@@ -23,6 +23,13 @@ namespace Microsoft.Azure.Commands.RecoveryServices.Backup.Cmdlets.ServiceClient
 {
     public partial class ServiceClientAdapter
     {
+        /// <summary>
+        /// Creates a new protected item or updates an already existing protected item
+        /// </summary>
+        /// <param name="containerName">Name of the container which this item belongs to</param>
+        /// <param name="protectedItemName">Name of the item</param>
+        /// <param name="request">Protected item create or update request</param>
+        /// <returns>Job created in the service for this operation</returns>
         public BaseRecoveryServicesJobResponse CreateOrUpdateProtectedItem(
                 string containerName,
                 string protectedItemName,
@@ -42,6 +49,12 @@ public BaseRecoveryServicesJobResponse CreateOrUpdateProtectedItem(
                                      BmsAdapter.CmdletCancellationToken).Result;
         }
 
+        /// <summary>
+        /// Deletes a protected item
+        /// </summary>
+        /// <param name="containerName">Name of the container which this item belongs to</param>
+        /// <param name="protectedItemName">Name of the item</param>
+        /// <returns>Job created in the service for this operation</returns>
         public BaseRecoveryServicesJobResponse DeleteProtectedItem(
                 string containerName,
                 string protectedItemName)
@@ -59,6 +72,13 @@ public BaseRecoveryServicesJobResponse DeleteProtectedItem(
                                      BmsAdapter.CmdletCancellationToken).Result;
         }
 
+        /// <summary>
+        /// Gets a protected item
+        /// </summary>
+        /// <param name="containerName">Name of the container which this item belongs to</param>
+        /// <param name="protectedItemName">Name of the item</param>
+        /// <param name="queryFilter">Query filter</param>
+        /// <returns>Protected item</returns>
         public ProtectedItemResponse GetProtectedItem(
                 string containerName,
                 string protectedItemName,
@@ -78,6 +98,13 @@ public ProtectedItemResponse GetProtectedItem(
                                      BmsAdapter.CmdletCancellationToken).Result;
         }
 
+        /// <summary>
+        /// List protected items protected by the Recovery Services vault according to the query params 
+        /// and pagination params.
+        /// </summary>
+        /// <param name="queryFilter">Query params</param>
+        /// <param name="paginationParams">Pagination params</param>
+        /// <returns>List of protected items</returns>
         public ProtectedItemListResponse ListProtectedItem(
                 ProtectedItemListQueryParam queryFilter,
             PaginationRequest paginationParams = null)

src/ResourceManager/RecoveryServices.Backup/Commands.RecoveryServices.Backup.ServiceClientAdapter/BMSAPIs/JobAPIs.cs

@@ -19,6 +19,11 @@ namespace Microsoft.Azure.Commands.RecoveryServices.Backup.Cmdlets.ServiceClient
 {
     public partial class ServiceClientAdapter
     {
+        /// <summary>
+        /// Gets a job
+        /// </summary>
+        /// <param name="jobId">ID of the job</param>
+        /// <returns>Job response returned by the service</returns>
         public JobResponse GetJob(string jobId)
         {
             string resourceName = BmsAdapter.GetResourceName();
@@ -32,6 +37,18 @@ public JobResponse GetJob(string jobId)
                 BmsAdapter.CmdletCancellationToken).Result;
         }
 
+        /// <summary>
+        /// Lists jobs according to the parameters
+        /// </summary>
+        /// <param name="jobId">ID of the job</param>
+        /// <param name="status">Status of the job</param>
+        /// <param name="operation">Operation represented by the job</param>
+        /// <param name="startTime">Time when the job started</param>
+        /// <param name="endTime">Time when the job finished</param>
+        /// <param name="backupManagementType">Backup management type of the item represented by the job</param>
+        /// <param name="top">Top pagination param</param>
+        /// <param name="skipToken">Skip token pagination param</param>
+        /// <returns>Job list response from the service</returns>
         public JobListResponse GetJobs(
             string jobId,
             string status,
@@ -73,6 +90,11 @@ public JobListResponse GetJobs(
                 BmsAdapter.CmdletCancellationToken).Result;
         }
 
+        /// <summary>
+        /// Cancels a job
+        /// </summary>
+        /// <param name="jobId">ID of the job to cancel</param>
+        /// <returns>Cancelled job response from the service</returns>
         public BaseRecoveryServicesJobResponse CancelJob(string jobId)
         {
             string resourceName = BmsAdapter.GetResourceName();
@@ -86,6 +108,12 @@ public BaseRecoveryServicesJobResponse CancelJob(string jobId)
                 BmsAdapter.CmdletCancellationToken).Result;
         }
 
+        /// <summary>
+        /// Gets the job operation status
+        /// </summary>
+        /// <param name="jobId">ID of the job</param>
+        /// <param name="operationId">ID of the operation associated with the job</param>
+        /// <returns>Job response returned by the service</returns>
         public JobResponse GetJobOperationStatus(string jobId, string operationId)
         {
             string resourceName = BmsAdapter.GetResourceName();
@@ -102,6 +130,16 @@ public JobResponse GetJobOperationStatus(string jobId, string operationId)
 
         #region private helpers
 
+        /// <summary>
+        /// Constructs the query object based on the input parameters
+        /// </summary>
+        /// <param name="backupManagementType">Backup management type of the item associated with the job</param>
+        /// <param name="startTime">Time when the job started</param>
+        /// <param name="endTime">Time when the job ended</param>
+        /// <param name="jobId">ID of the job</param>
+        /// <param name="status">Status of the job</param>
+        /// <param name="operation">ID of operation associated with the job</param>
+        /// <returns></returns>
         public CommonJobQueryFilters GetQueryObject(
             string backupManagementType,
             DateTime startTime,

src/ResourceManager/RecoveryServices.Backup/Commands.RecoveryServices.Backup.ServiceClientAdapter/BMSAPIs/OperationStatusAPIs.cs

@@ -23,6 +23,11 @@ namespace Microsoft.Azure.Commands.RecoveryServices.Backup.Cmdlets.ServiceClient
 {
     public partial class ServiceClientAdapter
     {
+        /// <summary>
+        /// Gets result of the refresh container operation using the operation tracking URL
+        /// </summary>
+        /// <param name="operationResultLink">Operation tracking URL</param>
+        /// <returns>Job response returned by the service</returns>
         public BaseRecoveryServicesJobResponse GetRefreshContainerOperationResultByURL(
                 string operationResultLink)
         {
@@ -34,6 +39,11 @@ public BaseRecoveryServicesJobResponse GetRefreshContainerOperationResultByURL(
                                      BmsAdapter.CmdletCancellationToken).Result;
         }
 
+        /// <summary>
+        /// Gets result of a generic operation on the protected item using the operation tracking URL
+        /// </summary>
+        /// <param name="operationResultLink">Operation tracking URL</param>
+        /// <returns>Operation status response returned by the service</returns>
         public BackUpOperationStatusResponse GetProtectedItemOperationStatusByURL(
                 string operationResultLink)
         {

src/ResourceManager/RecoveryServices.Backup/Commands.RecoveryServices.Backup.ServiceClientAdapter/BMSAPIs/PolicyAPIs.cs

@@ -23,6 +23,12 @@ namespace Microsoft.Azure.Commands.RecoveryServices.Backup.Cmdlets.ServiceClient
 {
     public partial class ServiceClientAdapter
     {
+        /// <summary>
+        /// Creates a new policy or updates an already existing policy
+        /// </summary>
+        /// <param name="policyName">Name of the policy</param>
+        /// <param name="request">Policy create or update request</param>
+        /// <returns>Policy created by this operation</returns>
         public ProtectionPolicyResponse CreateOrUpdateProtectionPolicy(
                 string policyName,
                 ProtectionPolicyRequest request)
@@ -36,6 +42,11 @@ public ProtectionPolicyResponse CreateOrUpdateProtectionPolicy(
                                      BmsAdapter.CmdletCancellationToken).Result;            
         }
 
+        /// <summary>
+        /// Gets a protection policy given the name
+        /// </summary>
+        /// <param name="policyName">Name of the policy</param>
+        /// <returns>Policy response returned by the service</returns>
         public ProtectionPolicyResponse GetProtectionPolicy(string policyName)
         {
             return BmsAdapter.Client.ProtectionPolicies.GetAsync(
@@ -46,6 +57,11 @@ public ProtectionPolicyResponse GetProtectionPolicy(string policyName)
                                      BmsAdapter.CmdletCancellationToken).Result;
         }
 
+        /// <summary>
+        /// Lists protection policies according to the input query filter
+        /// </summary>
+        /// <param name="queryFilter">Query filter</param>
+        /// <returns>List of protection policies</returns>
         public ProtectionPolicyListResponse ListProtectionPolicy(
                                             ProtectionPolicyQueryParameters queryFilter)
         {           
@@ -57,6 +73,11 @@ public ProtectionPolicyListResponse ListProtectionPolicy(
                                      BmsAdapter.CmdletCancellationToken).Result;
         }
 
+        /// <summary>
+        /// Gets protection policy operation status using the operation tracking URL
+        /// </summary>
+        /// <param name="url">Operation tracking URL</param>
+        /// <returns>Operation status response returned by the service</returns>
         public BackUpOperationStatusResponse GetProtectionPolicyOperationStatusByURL(string url)
         {
             return BmsAdapter.Client.GetOperationStatusByURLAsync(
@@ -65,6 +86,10 @@ public BackUpOperationStatusResponse GetProtectionPolicyOperationStatusByURL(str
                               BmsAdapter.CmdletCancellationToken).Result;                              
         }
 
+        /// <summary>
+        /// Deletes protection policy from the vault specified by the name
+        /// </summary>
+        /// <param name="policyName">Name of the policy to be deleted</param>
         public AzureOperationResponse RemoveProtectionPolicy(
                 string policyName)
         {

src/ResourceManager/RecoveryServices.Backup/Commands.RecoveryServices.Backup.ServiceClientAdapter/BMSAPIs/ProtectableItemAPI.cs

@@ -23,6 +23,12 @@ namespace Microsoft.Azure.Commands.RecoveryServices.Backup.Cmdlets.ServiceClient
 {
     public partial class ServiceClientAdapter
     {
+        /// <summary>
+        /// Lists protectable items according to the query filter and the pagination params
+        /// </summary>
+        /// <param name="queryFilter">Query filter</param>
+        /// <param name="paginationRequest">Pagination parameters</param>
+        /// <returns>List of protectable items</returns>
         public ProtectableObjectListResponse ListProtectableItem(
                 ProtectableObjectListQueryParameters queryFilter,
                 PaginationRequest paginationRequest = null)
@@ -39,6 +45,12 @@ public ProtectableObjectListResponse ListProtectableItem(
                                      BmsAdapter.CmdletCancellationToken).Result;
         }
 
+        /// <summary>
+        /// Triggers backup on the specified item
+        /// </summary>
+        /// <param name="containerName">Name of the container which this item belongs to</param>
+        /// <param name="itemName">Name of the item</param>
+        /// <returns>Job created by this operation</returns>
         public BaseRecoveryServicesJobResponse TriggerBackup(string containerName, string itemName)
         {
             return BmsAdapter.Client.Backups.TriggerBackupAsync(

src/ResourceManager/RecoveryServices.Backup/Commands.RecoveryServices.Backup.ServiceClientAdapter/BMSAPIs/RecoveryPointsAPIs.cs

@@ -23,7 +23,13 @@ namespace Microsoft.Azure.Commands.RecoveryServices.Backup.Cmdlets.ServiceClient
 {
     public partial class ServiceClientAdapter
     {
-        
+        /// <summary>
+        /// Gets detail about the recovery point identified by the input parameters
+        /// </summary>
+        /// <param name="containerName">Name of the container which the item belongs to</param>
+        /// <param name="protectedItemName">Name of the item</param>
+        /// <param name="recoveryPointId">ID of the recovery point</param>
+        /// <returns>Recovery point response returned by the service</returns>
         public RecoveryPointResponse GetRecoveryPointDetails
             (
             string containerName, 
@@ -47,7 +53,13 @@ string recoveryPointId
             return response;
         }
 
-        
+        /// <summary>
+        /// Lists recovery points according to the input parameters
+        /// </summary>
+        /// <param name="containerName">Name of the container which the item belongs to</param>
+        /// <param name="protectedItemName">Name of the item</param>
+        /// <param name="queryFilter">Query filter</param>
+        /// <returns>List of recovery points</returns>
         public RecoveryPointListResponse GetRecoveryPoints
             (
             string containerName, 

src/ResourceManager/RecoveryServices.Backup/Commands.RecoveryServices.Backup.ServiceClientAdapter/BMSAPIs/RestoreDiskAPIs.cs

@@ -25,7 +25,14 @@ namespace Microsoft.Azure.Commands.RecoveryServices.Backup.Cmdlets.ServiceClient
 {
     public partial class ServiceClientAdapter
     {
-        
+        /// <summary>
+        /// Restores the disk based on the recovery point and other input parameters
+        /// </summary>
+        /// <param name="rp">Recovery point to restore the disk to</param>
+        /// <param name="storageAccountId">ID of the storage account where to restore the disk</param>
+        /// <param name="storageAccountLocation">Location of the storage account where to restore the disk</param>
+        /// <param name="storageAccountType">Type of the storage account where to restore the disk</param>
+        /// <returns>Job created by this operation</returns>
         public BaseRecoveryServicesJobResponse RestoreDisk(AzureVmRecoveryPoint rp, string storageAccountId, 
             string storageAccountLocation, string storageAccountType)
         {

src/ResourceManager/RecoveryServices.Backup/Commands.RecoveryServices.Backup.ServiceClientAdapter/ClientProxy.cs

@@ -36,7 +36,7 @@ public partial class ClientProxy<TClient, THeader> : ClientProxyBase
         private Func<string, THeader> CustomRequestHeaderGenerator;
 
         /// <summary>
-        /// Get Azure backup client.
+        /// Get Recovery Services Backup service client.
         /// </summary>
         public TClient Client
         {
@@ -57,6 +57,9 @@ public ClientProxy(Func<string, THeader> headerGenerator, params object[] parame
             CustomRequestHeaderGenerator = headerGenerator;
         }
 
+        /// <summary>
+        /// Gets customer request headers
+        /// </summary>
         public THeader GetCustomRequestHeaders()
         {
             return CustomRequestHeaderGenerator(this.ClientRequestId);

src/ResourceManager/RecoveryServices.Backup/Commands.RecoveryServices.Backup.ServiceClientAdapter/ClientProxyBase.cs

@@ -49,6 +49,9 @@ public ClientProxyBase(params object[] parameters)
             ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };
         }
 
+        /// <summary>
+        /// Assigns a new client request ID to be used in each service client call - for logging purposes
+        /// </summary>
         public void RefreshClientRequestId()
         {
             ClientRequestId = Guid.NewGuid().ToString() + "-" + DateTime.Now.ToUniversalTime().ToString("yyyy-MM-dd HH:mm:ssZ") + "-PS";
@@ -59,6 +62,10 @@ public string GetClientRequestId()
             return ClientRequestId;
         }
 
+        /// <summary>
+        /// Gets Recovery Services vault name from the vault context
+        /// </summary>
+        /// <returns></returns>
         public string GetResourceName()
         {
             if (string.IsNullOrEmpty(PSRecoveryServicesClient.arsVault.Name))
@@ -68,6 +75,10 @@ public string GetResourceName()
             return PSRecoveryServicesClient.arsVault.Name;
         }
 
+        /// <summary>
+        /// Gets Recovery Services Vault's resource group name from the vault context
+        /// </summary>
+        /// <returns></returns>
         public string GetResourceGroupName()
         {
             if (string.IsNullOrEmpty(PSRecoveryServicesClient.arsVault.ResouceGroupName))
@@ -77,6 +88,10 @@ public string GetResourceGroupName()
             return PSRecoveryServicesClient.arsVault.ResouceGroupName;
         }
 
+        /// <summary>
+        /// Gets Recovery Services Vault's location from the vault context
+        /// </summary>
+        /// <returns></returns>
         public string GetResourceLocation()
         {
             if (string.IsNullOrEmpty(PSRecoveryServicesClient.arsVault.Location))