DocC setup (#22)

Author: yim-lee

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version:5.4
+// swift-tools-version:5.6
 
 import PackageDescription
 
@@ -7,7 +7,9 @@ let package = Package(
     products: [
         .library(name: "AWSLambdaEvents", targets: ["AWSLambdaEvents"]),
     ],
-    dependencies: [],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
+    ],
     targets: [
         .target(name: "AWSLambdaEvents", dependencies: []),
         .testTarget(name: "AWSLambdaEventsTests", dependencies: ["AWSLambdaEvents"]),

[email protected]

@@ -0,0 +1,15 @@
+// swift-tools-version:5.4
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-aws-lambda-events",
+    products: [
+        .library(name: "AWSLambdaEvents", targets: ["AWSLambdaEvents"]),
+    ],
+    dependencies: [],
+    targets: [
+        .target(name: "AWSLambdaEvents", dependencies: []),
+        .testTarget(name: "AWSLambdaEventsTests", dependencies: ["AWSLambdaEvents"]),
+    ]
+)

[email protected]

@@ -0,0 +1,15 @@
+// swift-tools-version:5.4
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-aws-lambda-events",
+    products: [
+        .library(name: "AWSLambdaEvents", targets: ["AWSLambdaEvents"]),
+    ],
+    dependencies: [],
+    targets: [
+        .target(name: "AWSLambdaEvents", dependencies: []),
+        .testTarget(name: "AWSLambdaEventsTests", dependencies: ["AWSLambdaEvents"]),
+    ]
+)

Sources/AWSLambdaEvents/ALB.swift

@@ -15,9 +15,9 @@
 import class Foundation.JSONEncoder
 
 // https://github.com/aws/aws-lambda-go/blob/master/events/alb.go
-/// ALBTargetGroupRequest contains data originating from the ALB Lambda target group integration
+/// `ALBTargetGroupRequest` contains data originating from the ALB Lambda target group integration.
 public struct ALBTargetGroupRequest: Codable {
-    /// ALBTargetGroupRequestContext contains the information to identify the load balancer invoking the lambda
+    /// `Context` contains information to identify the load balancer invoking the lambda.
     public struct Context: Codable {
         public let elb: ELBContext
     }
@@ -26,14 +26,14 @@ public struct ALBTargetGroupRequest: Codable {
     public let path: String
     public let queryStringParameters: [String: String]
 
-    /// Depending on your configuration of your target group either `headers` or `multiValueHeaders`
+    /// Depending on your configuration of your target group either ``headers`` or ``multiValueHeaders``
     /// are set.
     ///
     /// For more information visit:
     /// https://docs.aws.amazon.com/elasticloadbalancing/latest/application/lambda-functions.html#multi-value-headers
     public let headers: HTTPHeaders?
 
-    /// Depending on your configuration of your target group either `headers` or `multiValueHeaders`
+    /// Depending on your configuration of your target group either ``headers`` or ``multiValueHeaders``
     /// are set.
     ///
     /// For more information visit:
@@ -43,7 +43,7 @@ public struct ALBTargetGroupRequest: Codable {
     public let isBase64Encoded: Bool
     public let body: String?
 
-    /// ELBContext contains the information to identify the ARN invoking the lambda
+    /// `ELBContext` contains information to identify the ARN invoking the lambda.
     public struct ELBContext: Codable {
         public let targetGroupArn: String
     }

Sources/AWSLambdaEvents/APIGateway+V2.swift

@@ -12,9 +12,9 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// APIGatewayV2Request contains data coming from the new HTTP API Gateway
+/// `APIGatewayV2Request` contains data coming from the new HTTP API Gateway.
 public struct APIGatewayV2Request: Codable {
-    /// Context contains the information to identify the AWS account and resources invoking the Lambda function.
+    /// `Context` contains information to identify the AWS account and resources invoking the Lambda function.
     public struct Context: Codable {
         public struct HTTP: Codable {
             public let method: HTTPMethod
@@ -24,9 +24,9 @@ public struct APIGatewayV2Request: Codable {
             public let userAgent: String
         }
 
-        /// Authorizer contains authorizer information for the request context.
+        /// `Authorizer` contains authorizer information for the request context.
         public struct Authorizer: Codable {
-            /// JWT contains JWT authorizer information for the request context.
+            /// `JWT` contains JWT authorizer information for the request context.
             public struct JWT: Codable {
                 public let claims: [String: String]?
                 public let scopes: [String]?

Sources/AWSLambdaEvents/APIGateway.swift

@@ -17,7 +17,7 @@ import class Foundation.JSONEncoder
 // https://docs.aws.amazon.com/lambda/latest/dg/services-apigateway.html
 // https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html
 
-/// APIGatewayRequest contains data coming from the API Gateway
+/// `APIGatewayRequest` contains data coming from the API Gateway.
 public struct APIGatewayRequest: Codable {
     public struct Context: Codable {
         public struct Identity: Codable {

Sources/AWSLambdaEvents/Docs.docc/index.md

@@ -0,0 +1,40 @@
+# ``AWSLambdaEvents``
+
+A supporting library for Swift AWS Lambda Runtime.
+
+## Overview
+
+Swift AWS Lambda Runtime was designed to make building Lambda functions in Swift simple and safe. The library is an implementation of the [AWS Lambda Runtime API](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-custom.html) and uses an embedded asynchronous HTTP Client based on [SwiftNIO](http://github.com/apple/swift-nio) that is fine-tuned for performance in the AWS Runtime context. The library provides a multi-tier API that allows building a range of Lambda functions: From quick and simple closures to complex, performance-sensitive event handlers.
+
+Swift AWS Lambda Events is a supporting library for the [Swift AWS Lambda Runtime](http://github.com/swift-server/swift-aws-lambda-runtime) library, providing abstractions for popular AWS events.
+
+## Integration with AWS Platform Events
+
+AWS Lambda functions can be invoked directly from the AWS Lambda console UI, AWS Lambda API, AWS SDKs, AWS CLI, and AWS toolkits. More commonly, they are invoked as a reaction to an events coming from the AWS platform. To make it easier to integrate with AWS platform events, this library includes an `AWSLambdaEvents` target which provides abstractions for many commonly used events. Additional events can be easily modeled when needed following the same patterns set by `AWSLambdaEvents`. Integration points with the AWS Platform include:
+
+* [APIGateway Proxy](https://docs.aws.amazon.com/lambda/latest/dg/services-apigateway.html)
+* [S3 Events](https://docs.aws.amazon.com/lambda/latest/dg/with-s3.html)
+* [SES Events](https://docs.aws.amazon.com/lambda/latest/dg/services-ses.html)
+* [SNS Events](https://docs.aws.amazon.com/lambda/latest/dg/with-sns.html)
+* [SQS Events](https://docs.aws.amazon.com/lambda/latest/dg/with-sqs.html)
+* [CloudWatch Events](https://docs.aws.amazon.com/lambda/latest/dg/services-cloudwatchevents.html)
+
+**Note**: Each one of the integration points mentioned above includes a set of `Codable` structs that mirror AWS' data model for these APIs.
+
+## Getting started
+
+If you have never used AWS Lambda or Docker before, check out this [getting started guide](https://fabianfett.de/getting-started-with-swift-aws-lambda-runtime) which helps you with every step from zero to a running Lambda.
+
+Swift AWS Lambda Events is a supporting library for the [Swift AWS Lambda Runtime](http://github.com/swift-server/swift-aws-lambda-runtime) library, where you can find further documentation and examples.
+
+## Topics
+
+### Events
+
+- ``AppSyncEvent``
+- ``CloudwatchEvent``
+- ``DynamoDBEvent``
+- ``S3Event``
+- ``SESEvent``
+- ``SNSEvent``
+- ``SQSEvent``

Sources/AWSLambdaEvents/DynamoDB.swift

@@ -52,13 +52,13 @@ public struct DynamoDBEvent: Decodable {
     }
 
     public enum StreamViewType: String, Codable {
-        /// the entire item, as it appeared after it was modified.
+        /// The entire item, as it appeared after it was modified.
         case newImage = "NEW_IMAGE"
-        /// the entire item, as it appeared before it was modified.
+        /// The entire item, as it appeared before it was modified.
         case oldImage = "OLD_IMAGE"
-        /// both the new and the old item images of the item.
+        /// Both the new and the old item images of the item.
         case newAndOldImages = "NEW_AND_OLD_IMAGES"
-        /// only the key attributes of the modified item.
+        /// Only the key attributes of the modified item.
         case keysOnly = "KEYS_ONLY"
     }
 
@@ -75,32 +75,32 @@ public struct DynamoDBEvent: Decodable {
         public let eventId: String
 
         /// The type of data modification that was performed on the DynamoDB table:
-        ///  * INSERT - a new item was added to the table.
-        ///  * MODIFY - one or more of an existing item's attributes were modified.
-        ///  * REMOVE - the item was deleted from the table
+        ///  * `INSERT` - a new item was added to the table.
+        ///  * `MODIFY` - one or more of an existing item's attributes were modified.
+        ///  * `REMOVE` - the item was deleted from the table.
         public let eventName: OperationType
 
         /// The AWS service from which the stream record originated. For DynamoDB Streams,
-        /// this is aws:dynamodb.
+        /// this is `aws:dynamodb`.
         public let eventSource: String
 
         /// The version number of the stream record format. This number is updated whenever
         /// the structure of Record is modified.
         ///
-        /// Client applications must not assume that eventVersion will remain at a particular
-        /// value, as this number is subject to change at any time. In general, eventVersion
+        /// Client applications must not assume that `eventVersion` will remain at a particular
+        /// value, as this number is subject to change at any time. In general, `eventVersion`
         /// will only increase as the low-level DynamoDB Streams API evolves.
         public let eventVersion: String
 
-        /// The event source ARN of DynamoDB
+        /// The event source ARN of DynamoDB.
         public let eventSourceArn: String
 
         /// Items that are deleted by the Time to Live process after expiration have
         /// the following fields:
-        ///  * Records[].userIdentity.type
+        ///  * `Records[].userIdentity.type`
         ///
         /// "Service"
-        ///  * Records[].userIdentity.principalId
+        ///  * `Records[].userIdentity.principalId`
         ///
         /// "dynamodb.amazonaws.com"
         public let userIdentity: UserIdentity?

scripts/preview_docc.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+##===----------------------------------------------------------------------===##
+##
+## This source file is part of the SwiftAWSLambdaRuntime open source project
+##
+## Copyright (c) 2022 Apple Inc. and the SwiftAWSLambdaRuntime project authors
+## Licensed under Apache License v2.0
+##
+## See LICENSE.txt for license information
+## See CONTRIBUTORS.txt for the list of SwiftAWSLambdaRuntime project authors
+##
+## SPDX-License-Identifier: Apache-2.0
+##
+##===----------------------------------------------------------------------===##
+
+##===----------------------------------------------------------------------===##
+##
+## This source file is part of the Swift Distributed Actors open source project
+##
+## Copyright (c) 2018-2019 Apple Inc. and the Swift Distributed Actors project authors
+## Licensed under Apache License v2.0
+##
+## See LICENSE.txt for license information
+## See CONTRIBUTORS.md for the list of Swift Distributed Actors project authors
+##
+## SPDX-License-Identifier: Apache-2.0
+##
+##===----------------------------------------------------------------------===##
+
+swift package --disable-sandbox preview-documentation --target $1

scripts/soundness.sh

@@ -3,7 +3,7 @@
 ##
 ## This source file is part of the SwiftAWSLambdaRuntime open source project
 ##
-## Copyright (c) 2017-2018 Apple Inc. and the SwiftAWSLambdaRuntime project authors
+## Copyright (c) 2017-2022 Apple Inc. and the SwiftAWSLambdaRuntime project authors
 ## Licensed under Apache License v2.0
 ##
 ## See LICENSE.txt for license information
@@ -19,7 +19,7 @@ here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 
 function replace_acceptable_years() {
     # this needs to replace all acceptable forms with 'YEARS'
-    sed -e 's/2017-2018/YEARS/' -e 's/2017-2020/YEARS/' -e 's/2017-2021/YEARS/' -e 's/2017-2022/YEARS/' -e 's/2019/YEARS/' -e 's/2020/YEARS/'
+    sed -e 's/20[12][78901]-20[12][89012]/YEARS/' -e 's/2019/YEARS/' -e 's/202[012]/YEARS/'
 }
 
 printf "=> Checking for unacceptable language... "
@@ -61,7 +61,7 @@ for language in swift-or-c bash dtrace; do
   matching_files=( -name '*' )
   case "$language" in
       swift-or-c)
-        exceptions=( -name Package.swift )
+        exceptions=( -name Package.swift -o -name 'Package@*.swift' )
         matching_files=( -name '*.swift' -o -name '*.c' -o -name '*.h' )
         cat > "$tmp" <<"EOF"
 //===----------------------------------------------------------------------===//