Skip to content

Commit 28a60f2

Browse files
jalauzon-msftjalauzon-msft
authored
[Storage] [DataMovement] Add/update various docstrings (Azure#35589)
1 parent a65dba5 commit 28a60f2

File tree

8 files changed

+107
-193
lines changed

8 files changed

+107
-193
lines changed

‎sdk/storage/Azure.Storage.DataMovement/src/LocalTransferCheckpointer.cs‎

Lines changed: 10 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -52,15 +52,7 @@ public LocalTransferCheckpointer(string folderPath)
5252
_transferStates = new Dictionary<string, Dictionary<int, JobPartPlanFile>>();
5353
}
5454

55-
/// <summary>
56-
/// Adds a new transfer to the checkpointer.
57-
/// </summary>
58-
/// <param name="transferId"></param>
59-
/// <param name="cancellationToken">
60-
/// Optional <see cref="CancellationToken"/> to propagate
61-
/// notifications that the operation should be cancelled.
62-
/// </param>
63-
/// <returns></returns>
55+
/// <inheritdoc/>
6456
public override Task AddNewJobAsync(
6557
string transferId,
6658
CancellationToken cancellationToken = default)
@@ -78,20 +70,7 @@ public override Task AddNewJobAsync(
7870
return Task.CompletedTask;
7971
}
8072

81-
/// <summary>
82-
/// Adds a new transfer to the checkpointer.
83-
///
84-
/// If the transfer ID already exists, this method will throw an exception.
85-
/// </summary>
86-
/// <param name="transferId"></param>
87-
/// <param name="partNumber"></param>
88-
/// <param name="chunksTotal"></param>
89-
/// <param name="headerStream"></param>
90-
/// <param name="cancellationToken">
91-
/// Optional <see cref="CancellationToken"/> to propagate
92-
/// notifications that the operation should be cancelled.
93-
/// </param>
94-
/// <returns></returns>
73+
/// <inheritdoc/>
9574
public override async Task AddNewJobPartAsync(
9675
string transferId,
9776
int partNumber,
@@ -129,14 +108,7 @@ public override async Task AddNewJobPartAsync(
129108
}
130109
}
131110

132-
/// <summary>
133-
/// Add existing job to the checkpointer with verification. This function will throw
134-
/// if no existing job plan files exist in the checkpointer, and the job plan files have
135-
/// mismatch information from the information to resume from.
136-
/// </summary>
137-
/// <param name="transferId"></param>
138-
/// <param name="cancellationToken"></param>
139-
/// <returns></returns>
111+
/// <inheritdoc/>
140112
public override async Task AddExistingJobAsync(
141113
string transferId,
142114
CancellationToken cancellationToken = default)
@@ -196,13 +168,7 @@ public override async Task AddExistingJobAsync(
196168
}
197169
}
198170

199-
/// <summary>
200-
/// Gets the current number of chunk counts stored in the job part with the
201-
/// respective transfer id.
202-
/// </summary>
203-
/// <param name="transferId"></param>
204-
/// <param name="cancellationToken"></param>
205-
/// <returns></returns>
171+
/// <inheritdoc/>
206172
public override Task<int> CurrentJobPartCountAsync(
207173
string transferId,
208174
CancellationToken cancellationToken = default)
@@ -215,21 +181,7 @@ public override Task<int> CurrentJobPartCountAsync(
215181
throw Errors.MissingTransferIdCheckpointer(transferId);
216182
}
217183

218-
/// <summary>
219-
/// Creates a stream to the stored memory stored checkpointing information.
220-
/// </summary>
221-
/// <param name="transferId">The transfer ID.</param>
222-
/// <param name="partNumber">The part number of the current transfer.</param>
223-
/// <param name="readSize">
224-
/// The size of how many bytes to read.
225-
/// Specify 0 (zero) to create a stream that ends approximately at the end of the file.
226-
/// </param>
227-
/// <param name="offset">The offset of the current transfer.</param>
228-
/// <param name="cancellationToken">
229-
/// Optional <see cref="CancellationToken"/> to propagate
230-
/// notifications that the operation should be cancelled.
231-
/// </param>
232-
/// <returns>The Stream to the checkpoint of the respective job ID and part number.</returns>
184+
/// <inheritdoc/>
233185
public override async Task<Stream> ReadableStreamAsync(
234186
string transferId,
235187
int partNumber,
@@ -266,24 +218,7 @@ public override async Task<Stream> ReadableStreamAsync(
266218
}
267219
}
268220

269-
/// <summary>
270-
/// Writes to the checkpointer and stores the checkpointing information.
271-
///
272-
/// Creates the checkpoint file for the respective ID if it does not currently exist.
273-
///
274-
/// TODO: decide if we want to make this public, does not have a huge use to us currently.
275-
/// </summary>
276-
/// <param name="transferId">The transfer ID.</param>
277-
/// <param name="partNumber">The part number of the current transfer.</param>
278-
/// <param name="chunkIndex">The offset of the current transfer.</param>
279-
/// <param name="buffer">The buffer to write data from to the checkpoint.</param>
280-
/// <param name="cancellationToken">
281-
/// Optional <see cref="CancellationToken"/> to propagate
282-
/// notifications that the operation should be cancelled.
283-
/// </param>
284-
/// <returns></returns>
285-
/// <exception cref="ArgumentException"></exception>
286-
/// <exception cref="ArgumentNullException"></exception>
221+
/// <inheritdoc/>
287222
public override async Task WriteToCheckpointAsync(
288223
string transferId,
289224
int partNumber,
@@ -335,15 +270,7 @@ public override async Task WriteToCheckpointAsync(
335270
}
336271
}
337272

338-
/// <summary>
339-
/// Removes transfer information of the respective IDs.
340-
/// </summary>
341-
/// <param name="transferId">The transfer ID.</param>
342-
/// <param name="cancellationToken">
343-
/// Optional <see cref="CancellationToken"/> to propagate
344-
/// notifications that the operation should be cancelled.
345-
/// </param>
346-
/// <returns>Returns a bool that is true if operation is successful, otherwise is false.</returns>
273+
/// <inheritdoc/>
347274
public override Task<bool> TryRemoveStoredTransferAsync(string transferId, CancellationToken cancellationToken = default)
348275
{
349276
bool result = true;
@@ -376,26 +303,13 @@ public override Task<bool> TryRemoveStoredTransferAsync(string transferId, Cance
376303
return Task.FromResult(result);
377304
}
378305

379-
/// <summary>
380-
/// Lists all the transfers contained in the checkpointer.
381-
/// </summary>
382-
/// <param name="cancellationToken">
383-
/// Optional <see cref="CancellationToken"/> to propagate
384-
/// notifications that the operation should be cancelled.
385-
/// </param>
386-
/// <returns>The list of all the transfers contained in the checkpointer.</returns>
306+
/// <inheritdoc/>
387307
public override Task<List<string>> GetStoredTransfersAsync(CancellationToken cancellationToken = default)
388308
{
389309
return Task.FromResult(_transferStates.Keys.ToList());
390310
}
391311

392-
/// <summary>
393-
/// Sets the Job Transfer Status in the Job Part Plan files.
394-
/// </summary>
395-
/// <param name="transferId"></param>
396-
/// <param name="status"></param>
397-
/// <param name="cancellationToken"></param>
398-
/// <returns></returns>
312+
/// <inheritdoc/>
399313
public override async Task SetJobTransferStatusAsync(
400314
string transferId,
401315
StorageTransferStatus status,
@@ -437,14 +351,7 @@ public override async Task SetJobTransferStatusAsync(
437351
}
438352
}
439353

440-
/// <summary>
441-
/// Sets the Job Part Transfer Status in the Job Part Plan files.
442-
/// </summary>
443-
/// <param name="transferId"></param>
444-
/// <param name="partNumber"></param>
445-
/// <param name="status"></param>
446-
/// <param name="cancellationToken"></param>
447-
/// <returns></returns>
354+
/// <inheritdoc/>
448355
public override async Task SetJobPartTransferStatusAsync(
449356
string transferId,
450357
int partNumber,

‎sdk/storage/Azure.Storage.DataMovement/src/Models/ContainerTransferOptions.cs‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,19 @@
22
// Licensed under the MIT License.
33

44
using System;
5-
using System.Collections.Generic;
65
using System.ComponentModel;
7-
using System.Text;
86
using Azure.Core;
97

108
namespace Azure.Storage.DataMovement.Models
119
{
1210
/// <summary>
13-
/// <see cref="SingleTransferOptions"/> is used to provide options for parallel transfers.
11+
/// <see cref="ContainerTransferOptions"/> is used to provide options for parallel transfers
12+
/// of multiple resources in a container.
1413
/// </summary>
1514
public class ContainerTransferOptions : IEquatable<ContainerTransferOptions>
1615
{
1716
/// <summary>
18-
/// The maximum length of an transfer in bytes.
17+
/// The maximum length of a network transfer in bytes.
1918
///
2019
/// On uploads, if the value is not set, it will be set at 4 MB if the total size is less than 100MB
2120
/// or will default to 8 MB if the total size is greater than or equal to 100MB.

‎sdk/storage/Azure.Storage.DataMovement/src/Models/SingleTransferOptions.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,12 @@
88
namespace Azure.Storage.DataMovement.Models
99
{
1010
/// <summary>
11-
/// <see cref="SingleTransferOptions"/> is used to provide options for parallel transfers.
11+
/// <see cref="SingleTransferOptions"/> is used to provide options for a transfer of a single resource.
1212
/// </summary>
1313
public class SingleTransferOptions : IEquatable<SingleTransferOptions>
1414
{
1515
/// <summary>
16-
/// The maximum length of an transfer in bytes.
16+
/// The maximum length of a network transfer in bytes.
1717
///
1818
/// On uploads, if the value is not set, it will be set at 4 MB if the total size is less than 100MB
1919
/// or will default to 8 MB if the total size is greater than or equal to 100MB.

‎sdk/storage/Azure.Storage.DataMovement/src/Models/TransferCheckpointerOptions.cs‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,11 @@
11
// Copyright (c) Microsoft Corporation. All rights reserved.
22
// Licensed under the MIT License.
33

4-
using System;
5-
using System.Collections.Generic;
6-
using System.Text;
7-
84
namespace Azure.Storage.DataMovement.Models
95
{
106
/// <summary>
11-
/// Base Checkpointer class to create the checkpointing logic
12-
/// to resume from.
7+
/// Options for Checkpointer used for saving transfer state to allow for
8+
/// resuming a transfer.
139
/// </summary>
1410
public class TransferCheckpointerOptions
1511
{

‎sdk/storage/Azure.Storage.DataMovement/src/Shared/ErrorHandlingOptions.cs‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
11
// Copyright (c) Microsoft Corporation. All rights reserved.
22
// Licensed under the MIT License.
3+
34
using System;
4-
using System.Collections.Generic;
5-
using System.Text;
65

76
namespace Azure.Storage.DataMovement
87
{
98
/// <summary>
10-
/// Defines the Error Handling Path to take when a failure or error.
9+
/// Defines the Error Handling Path to take when a failure or error occurs.
1110
/// </summary>
1211
[Flags]
1312
public enum ErrorHandlingOptions

0 commit comments

Comments
 (0)