Skip to content

Commit bf30aaa

Browse files
brennanMKEbrennanMKE
authored
chore(Storage): add doc comments (#1280) (#1281)
* chore(Storage): add doc comments (#1280) * chore(Storage): document Operations aws-amplify/docs#2540
1 parent d60aa7f commit bf30aaa

16 files changed

+251
-13
lines changed

‎AmplifyPlugins/Storage/AWSS3StoragePlugin/AWSS3StoragePlugin+ClientBehavior.swift‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ extension AWSS3StoragePlugin {
4040
return getURLOperation
4141
}
4242

43-
/// Downloads to memory of the S3 object.
43+
/// Downloads S3 object into memory.
4444
///
4545
/// Stores the input in a storage request, constructs an operation to perform the work, queues it in the
4646
/// OperationQueue to perform the work asychronously.

‎AmplifyPlugins/Storage/AWSS3StoragePlugin/AWSS3StoragePlugin.swift‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,16 @@ import AWSPluginsCore
1212
// The AWSS3StoragePlugin which conforms to the Amplify plugin protocols and implements the Storage Plugin APIs for S3.
1313
final public class AWSS3StoragePlugin: StorageCategoryPlugin {
1414

15-
/// An instance of the S3 storage service
15+
/// An instance of the S3 storage service.
1616
var storageService: AWSS3StorageServiceBehaviour!
1717

18-
/// An instance of the authentication service
18+
/// An instance of the authentication service.
1919
var authService: AWSAuthServiceBehavior!
2020

2121
/// A queue that regulates the execution of operations.
2222
var queue: OperationQueue!
2323

24-
/// The default access level used for API calls
24+
/// The default access level used for API calls.
2525
var defaultAccessLevel: StorageAccessLevel!
2626

2727
/// The unique key of the plugin within the storage category.

‎AmplifyPlugins/Storage/AWSS3StoragePlugin/Dependency/AWSS3Adapter.swift‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,24 +8,33 @@
88
import Foundation
99
import AWSS3
1010

11-
/// The class confirming to AWSS3Behavior which uses an instance of the AWSS3 to perform its methods. This class acts
12-
/// as a wrapper to expose AWSS3 functionality through an instance over a singleton, and allows for mocking in unit
13-
/// tests. The methods contain no other logic other than calling the same method using the AWSS3 instance.
11+
/// The class conforming to AWSS3Behavior which uses an instance of the AWSS3 to perform its methods.
12+
/// This class acts as a wrapper to expose AWSS3 functionality through an instance over a singleton,
13+
/// and allows for mocking in unit tests. The methods contain no other logic other than calling the
14+
/// same method using the AWSS3 instance.
1415
class AWSS3Adapter: AWSS3Behavior {
1516
let awsS3: AWSS3
1617

1718
init(_ awsS3: AWSS3) {
1819
self.awsS3 = awsS3
1920
}
2021

22+
/// Lists objects in the bucket specified by `request`.
23+
/// - Parameter request: request identifying bucket and options
24+
/// - Returns: task
2125
public func listObjectsV2(_ request: AWSS3ListObjectsV2Request) -> AWSTask<AWSS3ListObjectsV2Output> {
2226
return awsS3.listObjectsV2(request)
2327
}
2428

29+
/// Deletes object identify by request.
30+
/// - Parameter request: request identifying object
31+
/// - Returns: task
2532
public func deleteObject(_ request: AWSS3DeleteObjectRequest) -> AWSTask<AWSS3DeleteObjectOutput> {
2633
return awsS3.deleteObject(request)
2734
}
2835

36+
/// Instance of S3 service.
37+
/// - Returns: S3 service instance.
2938
public func getS3() -> AWSS3 {
3039
return awsS3
3140
}

‎AmplifyPlugins/Storage/AWSS3StoragePlugin/Dependency/AWSS3Behavior.swift‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,12 @@ import AWSS3
1111
// Behavior that the implemenation class for AWSS3 will use.
1212
protocol AWSS3Behavior {
1313

14-
// List objects
14+
// Lists objects in a bucket.
1515
func listObjectsV2(_ request: AWSS3ListObjectsV2Request) -> AWSTask<AWSS3ListObjectsV2Output>
1616

17-
// Delete objects
17+
// Deletes object.
1818
func deleteObject(_ request: AWSS3DeleteObjectRequest) -> AWSTask<AWSS3DeleteObjectOutput>
1919

20-
// return the instance of AWSS3
20+
// Gets instance of AWS Service.
2121
func getS3() -> AWSS3
2222
}

‎AmplifyPlugins/Storage/AWSS3StoragePlugin/Dependency/AWSS3PreSignedURLBuilderAdapter.swift‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,15 @@ class AWSS3PreSignedURLBuilderAdapter: AWSS3PreSignedURLBuilderBehavior {
1616

1717
let preSignedURLBuilder: AWSS3PreSignedURLBuilder
1818

19+
/// Creates a pre-signed URL builder.
20+
/// - Parameter preSignedURLBuilder: Builder which can create a pre-signed URL.
1921
public init(_ preSignedURLBuilder: AWSS3PreSignedURLBuilder) {
2022
self.preSignedURLBuilder = preSignedURLBuilder
2123
}
2224

25+
/// Gets pre-signed URL.
26+
/// - Parameter getPreSignedURLRequest: Request.
27+
/// - Returns: Task.
2328
public func getPreSignedURL(_ getPreSignedURLRequest: AWSS3GetPreSignedURLRequest) -> AWSTask<NSURL> {
2429
return preSignedURLBuilder.getPreSignedURL(getPreSignedURLRequest)
2530
}

‎AmplifyPlugins/Storage/AWSS3StoragePlugin/Dependency/AWSS3PreSignedURLBuilderBehavior.swift‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,6 @@ import AWSS3
1111
// Behavior that the implemenation class for AWSS3PreSignedURLBuilder will use.
1212
protocol AWSS3PreSignedURLBuilderBehavior {
1313

14-
// Returns a task for getting a pre signed URL
14+
// Gets a pre-signed URL.
1515
func getPreSignedURL(_ getPreSignedURLRequest: AWSS3GetPreSignedURLRequest) -> AWSTask<NSURL>
1616
}

‎AmplifyPlugins/Storage/AWSS3StoragePlugin/Dependency/AWSS3TransferUtilityAdapter.swift‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,19 @@ class AWSS3TransferUtilityAdapter: AWSS3TransferUtilityBehavior {
1616

1717
let transferUtility: AWSS3TransferUtility
1818

19+
/// Creates a Transfer Utility Adapter.
20+
/// - Parameter transferUtility: Transfer Utility.
1921
public init(_ transferUtility: AWSS3TransferUtility) {
2022
self.transferUtility = transferUtility
2123
}
2224

25+
/// Downloads data.
26+
/// - Parameters:
27+
/// - fromBucket: Bucket.
28+
/// - key: Key.
29+
/// - expression: Expression.
30+
/// - completionHandler: Completion handler.
31+
/// - Returns: Task which provides the download task.
2332
public func downloadData(fromBucket: String,
2433
key: String,
2534
expression: AWSS3TransferUtilityDownloadExpression,
@@ -32,6 +41,15 @@ class AWSS3TransferUtilityAdapter: AWSS3TransferUtilityBehavior {
3241
completionHandler: completionHandler)
3342
}
3443

44+
45+
/// Downloads to a file.
46+
/// - Parameters:
47+
/// - fileURL: File URL.
48+
/// - bucket: Bucket.
49+
/// - key: Key.
50+
/// - expression: Expression.
51+
/// - completionHandler: Completion Handler
52+
/// - Returns: Task which provides the download task.
3553
public func download(to fileURL: URL,
3654
bucket: String,
3755
key: String,
@@ -46,7 +64,18 @@ class AWSS3TransferUtilityAdapter: AWSS3TransferUtilityBehavior {
4664
completionHandler: completionHandler)
4765
}
4866

67+
4968
// swiftlint:disable function_parameter_count
69+
70+
/// Uploads data.
71+
/// - Parameters:
72+
/// - data: Data.
73+
/// - bucket: Bucket.
74+
/// - key: Key.
75+
/// - contentType: Content Type.
76+
/// - expression: Expression.
77+
/// - completionHandler: Completion Handler.
78+
/// - Returns: Task which provides the upload task.
5079
public func uploadData(data: Data,
5180
bucket: String,
5281
key: String,
@@ -63,6 +92,15 @@ class AWSS3TransferUtilityAdapter: AWSS3TransferUtilityBehavior {
6392
completionHandler: completionHandler)
6493
}
6594

95+
/// Uploads file.
96+
/// - Parameters:
97+
/// - fileURL: File URL.
98+
/// - bucket: Bucket.
99+
/// - key: Key.
100+
/// - contentType: Content Type.
101+
/// - expression: Expression.
102+
/// - completionHandler: Completion Handler.
103+
/// - Returns: Task which provides the uplopad task.
66104
public func uploadFile(fileURL: URL,
67105
bucket: String,
68106
key: String,
@@ -79,6 +117,15 @@ class AWSS3TransferUtilityAdapter: AWSS3TransferUtilityBehavior {
79117
completionHandler: completionHandler)
80118
}
81119

120+
/// Uploads using multipart process.
121+
/// - Parameters:
122+
/// - fileURL: File URL,
123+
/// - bucket: Bucket.
124+
/// - key: Key.
125+
/// - contentType: Content Type.
126+
/// - expression: Expression.
127+
/// - completionHandler: Completion handler.
128+
/// - Returns: Task which provides multipart upload task.
82129
public func uploadUsingMultiPart(fileURL: URL,
83130
bucket: String,
84131
key: String,
@@ -95,6 +142,15 @@ class AWSS3TransferUtilityAdapter: AWSS3TransferUtilityBehavior {
95142
completionHandler: completionHandler)
96143
}
97144

145+
/// Uploads using multipart process.
146+
/// - Parameters:
147+
/// - data: Data.
148+
/// - bucket: Bucket.
149+
/// - key: Key.
150+
/// - contentType: Content Type.
151+
/// - expression: Expression.
152+
/// - completionHandler: Completion handle.
153+
/// - Returns: Task which provides the multipart upload task.
98154
public func uploadUsingMultiPart(data: Data,
99155
bucket: String,
100156
key: String,

‎AmplifyPlugins/Storage/AWSS3StoragePlugin/Operation/AWSS3StorageDownloadDataOperation.swift‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,11 @@ import Amplify
1010
import AWSPluginsCore
1111
import AWSS3
1212

13+
/// Storage Download Data Operation.
14+
///
15+
/// See: [Operations] for more details.
16+
///
17+
/// [Operations]: https://github.com/aws-amplify/amplify-ios/blob/main/OPERATIONS.md
1318
public class AWSS3StorageDownloadDataOperation: AmplifyInProcessReportingOperation<
1419
StorageDownloadDataRequest,
1520
Progress,
@@ -22,7 +27,7 @@ public class AWSS3StorageDownloadDataOperation: AmplifyInProcessReportingOperati
2227

2328
var storageTaskReference: StorageTaskReference?
2429

25-
/// Serial queue for synchronizing access to `storageTaskReference`.
30+
// Serial queue for synchronizing access to `storageTaskReference`.
2631
private let storageTaskActionQueue = DispatchQueue(label: "com.amazonaws.amplify.StorageTaskActionQueue")
2732

2833
init(_ request: StorageDownloadDataRequest,
@@ -40,27 +45,31 @@ public class AWSS3StorageDownloadDataOperation: AmplifyInProcessReportingOperati
4045
resultListener: resultListener)
4146
}
4247

48+
/// Pauses operation.
4349
override public func pause() {
4450
storageTaskActionQueue.async {
4551
self.storageTaskReference?.pause()
4652
super.pause()
4753
}
4854
}
4955

56+
/// Resumes operation.
5057
override public func resume() {
5158
storageTaskActionQueue.async {
5259
self.storageTaskReference?.resume()
5360
super.resume()
5461
}
5562
}
5663

64+
/// Cancels operation.
5765
override public func cancel() {
5866
storageTaskActionQueue.async {
5967
self.storageTaskReference?.cancel()
6068
super.cancel()
6169
}
6270
}
6371

72+
/// Performs the task to download data.
6473
override public func main() {
6574
if isCancelled {
6675
finish()

‎AmplifyPlugins/Storage/AWSS3StoragePlugin/Operation/AWSS3StorageDownloadFileOperation.swift‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,12 @@ import AWSS3
1212

1313
// TODO: thread safety: everything has to be locked down
1414
// TODO verify no retain cycle
15+
16+
/// Storage Download File Operation.
17+
///
18+
/// See: [Operations] for more details.
19+
///
20+
/// [Operations]: https://github.com/aws-amplify/amplify-ios/blob/main/OPERATIONS.md
1521
public class AWSS3StorageDownloadFileOperation: AmplifyInProcessReportingOperation<
1622
StorageDownloadFileRequest,
1723
Progress,
@@ -24,7 +30,7 @@ public class AWSS3StorageDownloadFileOperation: AmplifyInProcessReportingOperati
2430

2531
var storageTaskReference: StorageTaskReference?
2632

27-
/// Serial queue for synchronizing access to `storageTaskReference`.
33+
// Serial queue for synchronizing access to `storageTaskReference`.
2834
private let storageTaskActionQueue = DispatchQueue(label: "com.amazonaws.amplify.StorageTaskActionQueue")
2935

3036
init(_ request: StorageDownloadFileRequest,
@@ -42,27 +48,31 @@ public class AWSS3StorageDownloadFileOperation: AmplifyInProcessReportingOperati
4248
resultListener: resultListener)
4349
}
4450

51+
/// Pauses operation.
4552
override public func pause() {
4653
storageTaskActionQueue.async {
4754
self.storageTaskReference?.pause()
4855
super.pause()
4956
}
5057
}
5158

59+
/// Resumes operation.
5260
override public func resume() {
5361
storageTaskActionQueue.async {
5462
self.storageTaskReference?.resume()
5563
super.resume()
5664
}
5765
}
5866

67+
/// Cancels operation.
5968
override public func cancel() {
6069
storageTaskActionQueue.async {
6170
self.storageTaskReference?.cancel()
6271
super.cancel()
6372
}
6473
}
6574

75+
/// Performs the task to download file.
6676
override public func main() {
6777
if isCancelled {
6878
finish()

‎AmplifyPlugins/Storage/AWSS3StoragePlugin/Operation/AWSS3StorageGetURLOperation.swift‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,11 @@ import Amplify
1010
import AWSPluginsCore
1111
import AWSS3
1212

13+
/// Storage Get URL Operation.
14+
///
15+
/// See: [Operations] for more details.
16+
///
17+
/// [Operations]: https://github.com/aws-amplify/amplify-ios/blob/main/OPERATIONS.md
1318
public class AWSS3StorageGetURLOperation: AmplifyOperation<
1419
StorageGetURLRequest,
1520
URL,
@@ -32,10 +37,12 @@ public class AWSS3StorageGetURLOperation: AmplifyOperation<
3237
resultListener: resultListener)
3338
}
3439

40+
/// Cancels operation.
3541
override public func cancel() {
3642
super.cancel()
3743
}
3844

45+
/// Performs the task to get URL.
3946
override public func main() {
4047
if isCancelled {
4148
finish()

0 commit comments

Comments
 (0)