From 805e02a4d90a28941e9b841d4454511e406a9f7f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Stormacq?= Date: Fri, 25 Jul 2025 17:48:39 +0400 Subject: [PATCH 1/3] fix doc warnings --- .../AWSLambdaRuntime/Docs.docc/Deployment.md | 44 +++++------ .../Docs.docc/Proposals/0001-v2-api.md | 74 +++++++++---------- .../AWSLambdaRuntime/Docs.docc/quick-setup.md | 2 +- Sources/AWSLambdaRuntime/LambdaHandlers.swift | 1 + scripts/check-doc.sh | 59 +++++++++++++++ 5 files changed, 121 insertions(+), 59 deletions(-) create mode 100755 scripts/check-doc.sh diff --git a/Sources/AWSLambdaRuntime/Docs.docc/Deployment.md b/Sources/AWSLambdaRuntime/Docs.docc/Deployment.md index 7bfd8cce..245b1cc0 100644 --- a/Sources/AWSLambdaRuntime/Docs.docc/Deployment.md +++ b/Sources/AWSLambdaRuntime/Docs.docc/Deployment.md @@ -2,6 +2,8 @@ Learn how to deploy your Swift Lambda functions to AWS. +### Overview + There are multiple ways to deploy your Swift code to AWS Lambda. The very first time, you'll probably use the AWS Console to create a new Lambda function and upload your code as a zip file. However, as you iterate on your code, you'll want to automate the deployment process. To take full advantage of the cloud, we recommend using Infrastructure as Code (IaC) tools like the [AWS Serverless Application Model (SAM)](https://aws.amazon.com/serverless/sam/) or [AWS Cloud Development Kit (CDK)](https://aws.amazon.com/cdk/). These tools allow you to define your infrastructure and deployment process as code, which can be version-controlled and automated. @@ -19,7 +21,7 @@ Here is the content of this guide: * [Deploy your Lambda function with AWS Cloud Development Kit (CDK)](#deploy-your-lambda-function-with-aws-cloud-development-kit-cdk) * [Third-party tools](#third-party-tools) -## Prerequisites +### Prerequisites 1. Your AWS Account @@ -71,7 +73,7 @@ Here is the content of this guide: >[!NOTE] > When building on Linux, your current user must have permission to use docker. On most Linux distributions, you can do so by adding your user to the `docker` group with the following command: `sudo usermod -aG docker $USER`. You must log out and log back in for the changes to take effect. -## Choosing the AWS Region where to deploy +### Choosing the AWS Region where to deploy [AWS Global infrastructure](https://aws.amazon.com/about-aws/global-infrastructure/) spans over 34 geographic Regions (and continuously expanding). When you create a resource on AWS, such as a Lambda function, you have to select a geographic region where the resource will be created. The two main factors to consider to select a Region are the physical proximity with your users and geographical compliance. @@ -79,13 +81,13 @@ Physical proximity helps you reduce the network latency between the Lambda funct Geographical compliance, also known as data residency compliance, involves following location-specific regulations about how and where data can be stored and processed. -## The Lambda execution IAM role +### The Lambda execution IAM role A Lambda execution role is an AWS Identity and Access Management (IAM) role that grants your Lambda function the necessary permissions to interact with other AWS services and resources. Think of it as a security passport that determines what your function is allowed to do within AWS. For example, if your Lambda function needs to read files from Amazon S3, write logs to Amazon CloudWatch, or access an Amazon DynamoDB table, the execution role must include the appropriate permissions for these actions. When you create a Lambda function, you must specify an execution role. This role contains two main components: a trust policy that allows the Lambda service itself to assume the role, and permission policies that determine what AWS resources the function can access. By default, Lambda functions get basic permissions to write logs to CloudWatch Logs, but any additional permissions (like accessing S3 buckets or sending messages to SQS queues) must be explicitly added to the role's policies. Following the principle of least privilege, it's recommended to grant only the minimum permissions necessary for your function to operate, helping maintain the security of your serverless applications. -## Deploy your Lambda function with the AWS Console +### Deploy your Lambda function with the AWS Console In this section, we deploy the HelloWorld example function using the AWS Console. The HelloWorld function is a simple function that takes a `String` as input and returns a `String`. @@ -93,7 +95,7 @@ Authenticate on the AWS console using your IAM username and password. On the top ![Console - Select AWS Region](console-10-regions) -### Create the function +#### Create the function Select **Create a function** to create a function. @@ -118,7 +120,7 @@ Select **Save** You're now ready to test your function. -### Invoke the function +#### Invoke the function Select the **Test** tab in the console and prepare a payload to send to your Lambda function. In this example, you've deployed the [HelloWorld](Exmaples.HelloWorld/README.md) example function. As explained, the function takes a `String` as input and returns a `String`. we will therefore create a test event with a JSON payload that contains a `String`. @@ -150,7 +152,7 @@ REPORT RequestId: f789fbb6-10d9-4ba3-8a84-27aa283369a2 Duration: 1.12 ms Billed AWS lambda charges usage per number of invocations and the CPU time, rounded to the next millisecond. AWS Lambda offers a generous free-tier of 1 million invocation each month and 400,000 GB-seconds of compute time per month. See [Lambda pricing](https://aws.amazon.com/lambda/pricing/) for the details. -### Delete the function +#### Delete the function When you're finished with testing, you can delete the Lambda function and the IAM execution role that the console created automatically. @@ -164,13 +166,13 @@ Select the `HelloWorld-role-xxxx` role and select **Delete**. Confirm the deleti ![Console - delete IAM role](console-80-delete-role) -## Deploy your Lambda function with the AWS Command Line Interface (CLI) +### Deploy your Lambda function with the AWS Command Line Interface (CLI) You can deploy your Lambda function using the AWS Command Line Interface (CLI). The CLI is a unified tool to manage your AWS services from the command line and automate your operations through scripts. The CLI is available for Windows, macOS, and Linux. Follow the [installation](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) and [configuration](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) instructions in the AWS CLI User Guide. In this example, we're building the HelloWorld example from the [Examples](https://github.com/swift-server/swift-aws-lambda-runtime/tree/main/Examples) directory. -### Create the function +#### Create the function To create a function, you must first create the function execution role and define the permission. Then, you create the function with the `create-function` command. @@ -245,7 +247,7 @@ aws lambda update-function-code \ --zip-file fileb://.build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/MyLambda/MyLambda.zip ``` -### Invoke the function +#### Invoke the function Use the `invoke-function` command to invoke the function. You can pass a well-formed JSON payload as input to the function. The payload must be encoded in base64. The CLI returns the status code and stores the response in a file. @@ -263,7 +265,7 @@ cat out.txt rm out.txt ``` -### Delete the function +#### Delete the function To cleanup, first delete the Lambda funtion, then delete the IAM role. @@ -278,7 +280,7 @@ aws iam delete-role-policy --role-name lambda_basic_execution --policy-name lamb aws iam delete-role --role-name lambda_basic_execution ``` -## Deploy your Lambda function with AWS Serverless Application Model (SAM) +### Deploy your Lambda function with AWS Serverless Application Model (SAM) AWS Serverless Application Model (SAM) is an open-source framework for building serverless applications. It provides a simplified way to define the Amazon API Gateway APIs, AWS Lambda functions, and Amazon DynamoDB tables needed by your serverless application. You can define your serverless application in a single file, and SAM will use it to deploy your function and all its dependencies. @@ -286,7 +288,7 @@ To use SAM, you need to [install the SAM CLI](https://docs.aws.amazon.com/server Use SAM when you want to deploy more than a Lambda function. SAM helps you to create additional resources like an API Gateway, an S3 bucket, or a DynamoDB table, and manage the permissions between them. -### Create the function +#### Create the function We assume your Swift function is compiled and packaged, as described in the [Prerequisites](#prerequisites) section. @@ -375,7 +377,7 @@ Successfully created/updated stack - APIGAtewayLambda in us-east-1 To update your function or any other AWS service defined in your YAML file, you can use the `sam deploy` command without the `--guided` flag. -### Invoke the function +#### Invoke the function SAM allows you to invoke the function locally and remotely. @@ -427,7 +429,7 @@ Access logging is disabled for HTTP API ID (g9m53sn7xa) You can also tail the logs with the `-t, --tail` flag. -### Delete the function +#### Delete the function SAM allows you to delete your function and all infrastructure that is defined in the YAML template with just one command. @@ -443,7 +445,7 @@ Are you sure you want to delete the folder APIGatewayLambda in S3 which contains Deleted successfully ``` -## Deploy your Lambda function with the AWS Cloud Development Kit (CDK) +### Deploy your Lambda function with the AWS Cloud Development Kit (CDK) The AWS Cloud Development Kit is an open-source software development framework to define cloud infrastructure in code and provision it through AWS CloudFormation. The CDK provides high-level constructs that preconfigure AWS resources with best practices, and you can use familiar programming languages like TypeScript, Javascript, Python, Java, C#, and Go to define your infrastructure. @@ -453,7 +455,7 @@ Use the CDK when you want to define your infrastructure in code and manage the d This example deploys the [APIGateway]((https://github.com/swift-server/swift-aws-lambda-runtime/blob/main/Examples/APIGateway/) example code. It comprises a Lambda function that implements a REST API and an API Gateway to expose the function over HTTPS. -### Create a CDK project +#### Create a CDK project To create a new CDK project, use the `cdk init` command. The command creates a new directory with the project structure and the necessary files to define your infrastructure. @@ -523,7 +525,7 @@ import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations // ... ``` -### Deploy the infrastructure +#### Deploy the infrastructure To deploy the infrastructure, type the following commands. @@ -553,7 +555,7 @@ arn:aws:cloudformation:eu-central-1:012345678901:stack/LambdaApiStack/e0054390-b ✨ Total time: 45.84s ``` -### Invoke your Lambda function +#### Invoke your Lambda function To invoke the Lambda function, use this `curl` command line. @@ -609,7 +611,7 @@ curl -s https://tyqnjcawh0.execute-api.eu-central-1.amazonaws.com | jq } ``` -### Delete the infrastructure +#### Delete the infrastructure When done testing, you can delete the infrastructure with this command. @@ -622,6 +624,6 @@ LambdaApiStack: destroying... [1/1] ✅ LambdaApiStack: destroyed ``` -## Third-party tools +### Third-party tools We welcome contributions to this section. If you have experience deploying Swift Lambda functions with third-party tools like Serverless Framework, Terraform, or Pulumi, please share your knowledge with the community. \ No newline at end of file diff --git a/Sources/AWSLambdaRuntime/Docs.docc/Proposals/0001-v2-api.md b/Sources/AWSLambdaRuntime/Docs.docc/Proposals/0001-v2-api.md index 0396d48d..05dc8ea4 100644 --- a/Sources/AWSLambdaRuntime/Docs.docc/Proposals/0001-v2-api.md +++ b/Sources/AWSLambdaRuntime/Docs.docc/Proposals/0001-v2-api.md @@ -24,11 +24,11 @@ Versions: - Remove `~Copyable` from `LambdaResponseStreamWriter` and `LambdaResponseWriter`. Instead throw an error when `finish()` is called multiple times or when `write`/`writeAndFinish` is called after `finish()`. -## Motivation +### Motivation -### Current Limitations +#### Current Limitations -#### EventLoop interfaces +##### EventLoop interfaces The current API extensively uses the `EventLoop` family of interfaces from SwiftNIO in many areas. To use these interfaces correctly though, it requires developers to exercise great care and understand the various transform methods @@ -37,7 +37,7 @@ the code in the current API hard to reason about and maintain. For these reasons Server ecosystem is to shift to newer, more readable, Swift concurrency constructs and de-couple from SwiftNIO's `EventLoop` interfaces. -#### No ownership of the main() function +##### No ownership of the main() function A Lambda function can currently be implemented through conformance to the various handler protocols defined in ``AWSLambdaRuntime/LambdaHandler``. Each of these protocols have an extension which implements a `static func main()`. @@ -47,7 +47,7 @@ cannot override the default implementation. This has proven challenging for user [set up global properties before the Lambda starts-up](https://github.com/swift-server/swift-aws-lambda-runtime/issues/265). Setting up global properties is required to customize the Swift Logging, Metric and Tracing backend. -#### Non-trivial transition from SimpleLambdaHandler to LambdaHandler +##### Non-trivial transition from SimpleLambdaHandler to LambdaHandler The `SimpleLambdaHandler` protocol provides a quick and easy way to implement a basic Lambda function. It only requires an implementation of the `handle` function where the business logic of the Lambda function can be written. @@ -68,7 +68,7 @@ the Swift on Server ecosystem in order to cleanly manage the lifecycle of the se because the convenient `swift-service-lifecycle` v2 library — which is commonly used for cleanly managing the lifecycles of required services and widely supported by many libraries — cannot be used in a structured concurrency manner. -#### Does not integrate well with swift-service-lifecycle in a structured concurrency manner +##### Does not integrate well with swift-service-lifecycle in a structured concurrency manner The Lambda runtime can only be started using the **internal** `Lambda.run()` function. This function is called by the `main()` function defined by the `LambdaHandler` protocol, preventing users from injecting initialized services into the @@ -111,35 +111,35 @@ struct MyLambda: LambdaHandler { } ``` -#### Verbose Codable support +##### Verbose Codable support In the current API, there are extensions and Codable wrapper classes for decoding events and encoding computed responses for _each_ different handler protocol and for both `String` and `JSON` formats. This has resulted in a lot of boilerplate code which can very easily be made generic and simplified in v2. -### New features +#### New features -#### Support response streaming +##### Support response streaming In April 2023 [AWS introduced support for response streaming](https://aws.amazon.com/blogs/compute/introducing-aws-lambda-response-streaming/) in Lambda. The current API does not support streaming. For v2 we want to change this. -#### Scheduling background work +##### Scheduling background work In May [AWS described in a blog post that you can run background tasks in Lambda](https://aws.amazon.com/blogs/compute/running-code-after-returning-a-response-from-an-aws-lambda-function/) until the runtime asks for more work from the control plane. We want to support this by adding new API that allows background processing, even after the response has been returned. -## Proposed Solution +### Proposed Solution -### async/await-first API +#### async/await-first API Large parts of `Lambda`, `LambdaHandler`, and `LambdaRuntime` will be re-written to use async/await constructs in place of the `EventLoop` family of interfaces. -### Providing ownership of main() and support for swift-service-lifecycle +#### Providing ownership of main() and support for swift-service-lifecycle - Instead of conforming to a handler protocol, users can now create a `LambdaRuntime` by passing in a handler closure. - `LambdaRuntime` conforms to `ServiceLifecycle.Service` by implementing a `run()` method that contains initialization @@ -177,7 +177,7 @@ let serviceGroup = ServiceGroup( try await serviceGroup.run() ``` -### Simplifying Codable support +#### Simplifying Codable support A detailed explanation is provided in the **Codable Support** section. In short, much of the boilerplate code defined for each handler protocol in `Lambda+Codable` and `Lambda+String` will be replaced with a single `LambdaCodableAdapter` @@ -188,11 +188,11 @@ This adapter struct is generic over (1) any handler conforming to a new handler conforming to protocols `LambdaEventDecoder` and `LambdaOutputDecoder`. The adapter will wrap the underlying handler with encoding/decoding logic. -## Detailed Solution +### Detailed Solution Below are explanations for all types that we want to use in AWS Lambda Runtime v2. -### LambdaResponseStreamWriter +#### LambdaResponseStreamWriter We will introduce a new `LambdaResponseStreamWriter` protocol. It is used in the new `StreamingLambdaHandler` (defined below), which is the new base protocol for the `LambdaRuntime` (defined below as well). @@ -214,7 +214,7 @@ If the user does not call `finish()`, the library will automatically finish the Appropriate errors will be thrown if `finish()` is called multiple times, or if `write`/`writeAndFinish` is called after `finish()`. -### LambdaContext +#### LambdaContext `LambdaContext` will be largely unchanged, but the `eventLoop` property will be removed. The `allocator` property of type `ByteBufferAllocator` will also be removed because (1), we generally want to reduce the number of SwiftNIO types @@ -250,12 +250,12 @@ public struct LambdaContext: Sendable { } ``` -### Handlers +#### Handlers We introduce three handler protocols: `StreamingLambdaHandler`, `LambdaHandler`, and `LambdaWithBackgroundProcessingHandler`. -#### StreamingLambdaHandler +##### StreamingLambdaHandler The new `StreamingLambdaHandler` protocol is the base protocol to implement a Lambda function. Most users will not use this protocol and instead use the `LambdaHandler` protocol defined below. @@ -319,7 +319,7 @@ struct SendNumbersWithPause: StreamingLambdaHandler { } ``` -#### LambdaHandler: +##### LambdaHandler: This handler protocol will be the go-to choice for most use-cases because it is completely agnostic to any encoding/decoding logic -- conforming objects simply have to implement the `handle` function where the input and return @@ -344,7 +344,7 @@ public protocol LambdaHandler { } ``` -#### LambdaWithBackgroundProcessingHandler: +##### LambdaWithBackgroundProcessingHandler: This protocol is exactly like `LambdaHandler`, with the only difference being the added support for executing background work after the result has been sent to the AWS Lambda control plane. @@ -385,7 +385,7 @@ public protocol LambdaWithBackgroundProcessingHandler { } ``` -##### Example Usage: +###### Example Usage: ```swift struct BackgroundProcessingHandler: LambdaWithBackgroundProcessingHandler { @@ -418,7 +418,7 @@ struct BackgroundProcessingHandler: LambdaWithBackgroundProcessingHandler { } ``` -#### Handler Adapters +##### Handler Adapters Since the `StreamingLambdaHandler` protocol is the base protocol the `LambdaRuntime` works with, there are adapters to make both `LambdaHandler` and `LambdaWithBackgroundProcessingHandler` compatible with `StreamingLambdaHandler`. @@ -441,7 +441,7 @@ then through `LambdaCodableAdapter`. `LambdaWithBackgroundHandler` just requires For the common JSON-in and JSON-out use-case, there is an extension on `LambdaRuntime` that abstracts away this wrapping from the user. -### LambdaRuntime +#### LambdaRuntime `LambdaRuntime` is the class that communicates with the Lambda control plane as defined in [Building a custom runtime for AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-custom.html) and @@ -489,7 +489,7 @@ immediately crashes as the user will not have the `AWS_LAMBDA_RUNTIME_API` envir environment variable is an unnecessary step that can be avoided. In the v2 API, the `run()` function will automatically start the mock server when the `AWS_LAMBDA_RUNTIME_API` environment variable cannot be found. -### Lambda +#### Lambda We also add an enum to store a static function and a property on. We put this on the static `Lambda` because `LambdaRuntime` is generic and thus has bad ergonomics for static properties and functions. @@ -544,14 +544,14 @@ now being able to cleanly manage the lifecycles of required services in a struct > } > ``` -### Codable support +#### Codable support The `LambdaHandler` and `LambdaWithBackgroundProcessingHandler` protocols abstract away encoding/decoding logic from the conformers as they are generic over custom `Event` and `Output` types. We introduce two adapters `LambdaHandlerAdapter` and `CodableLambdaAdapter` that implement the encoding/decoding logic and in turn allow the respective handlers to conform to `StreamingLambdaHandler`. -#### LambdaHandlerAdapter +##### LambdaHandlerAdapter Any handler conforming to `LambdaHandler` can be conformed to `LambdaWithBackgroundProcessingHandler` through `LambdaHandlerAdapter`. @@ -575,13 +575,13 @@ public struct LambdaHandlerAdapter< } ``` -#### LambdaCodableAdapter +##### LambdaCodableAdapter `LambdaCodableAdapter` accepts any generic underlying handler conforming to `LambdaWithBackgroundProcessingHandler`. It also accepts _any_ encoder and decoder object conforming to the `LambdaEventDecoder` and `LambdaOutputEncoder` protocols: -##### LambdaEventDecoder and LambdaOutputEncoder protocols +###### LambdaEventDecoder and LambdaOutputEncoder protocols ```swift public protocol LambdaEventDecoder { @@ -651,13 +651,13 @@ public struct LambdaCodableAdapter< } ``` -### Handler as a Closure +#### Handler as a Closure To create a Lambda function using the current API, a user first has to create an object and conform it to one of the handler protocols by implementing the initializer and the `handle(...)` function. Now that `LambdaRuntime` is public, this verbosity can very easily be simplified. -#### ClosureHandler +##### ClosureHandler This handler is generic over any `Event` type conforming to `Decodable` and any `Output` type conforming to `Encodable` or `Void`. @@ -740,9 +740,9 @@ extension LambdaRuntime { } ``` -## Alternatives considered +### Alternatives considered -### [UInt8] instead of ByteBuffer +#### [UInt8] instead of ByteBuffer We considered using `[UInt8]` instead of `ByteBuffer` in the base `LambdaHandler` API. We decided to use `ByteBuffer` for two reasons. @@ -756,7 +756,7 @@ for two reasons. framework with Lambda (examples: Vapor, Hummingbird, ...). Those developers will most likely prefer to get the data in the `ByteBuffer` format anyway, as their lower level networking stack also depends on SwiftNIO. -### Users create a LambdaResponse, that supports streaming instead of being passed a LambdaResponseStreamWriter +#### Users create a LambdaResponse, that supports streaming instead of being passed a LambdaResponseStreamWriter Instead of passing the `LambdaResponseStreamWriter` in the invocation we considered a new type `LambdaResponse`, that users must return in the `StreamingLambdaHandler`. @@ -826,7 +826,7 @@ approach in which a `LambdaResponse` is returned can trivially be built on top o We welcome the discussion on this topic and are open to change our minds and API here. -### Adding a function `addBackgroundTask(_ body: sending @escaping () async -> ())` in `LambdaContext` +#### Adding a function `addBackgroundTask(_ body: sending @escaping () async -> ())` in `LambdaContext` Initially we proposed an explicit `addBackgroundTask(_:)` function in `LambdaContext` that users could call from their handler object to schedule a background task to be run after the result is reported to AWS. We received feedback that @@ -884,7 +884,7 @@ handler protocols: (with a single call to `writeAndFinish(_:)`). After closing the `LambdaResponseStreamWriter`, any background work can be implemented. -### Making LambdaResponseStreamWriter and LambdaResponseWriter ~Copyable +#### Making LambdaResponseStreamWriter and LambdaResponseWriter ~Copyable We initially proposed to make the `LambdaResponseStreamWriter` and `LambdaResponseWriter` protocols `~Copyable`, with the functions that close the response having the `consuming` ownership keyword. This was so that the compiler could @@ -897,7 +897,7 @@ function. Therefore, throwing appropriate errors to prevent abnormal interaction with the writers seems to be the simplest approach. -## A word about versioning +### A word about versioning We are aware that AWS Lambda Runtime has not reached a proper 1.0. We intend to keep the current implementation around at 1.0-alpha. We don't want to change the current API without releasing a new major. We think there are lots of adopters diff --git a/Sources/AWSLambdaRuntime/Docs.docc/quick-setup.md b/Sources/AWSLambdaRuntime/Docs.docc/quick-setup.md index bf2f6db4..a09c5309 100644 --- a/Sources/AWSLambdaRuntime/Docs.docc/quick-setup.md +++ b/Sources/AWSLambdaRuntime/Docs.docc/quick-setup.md @@ -10,7 +10,7 @@ For a detailed step-by-step instruction, follow the tutorial instead. For the impatient, keep reading. -## High-level instructions +### High-level instructions Follow these 6 steps to write, test, and deploy a Lambda function in Swift. diff --git a/Sources/AWSLambdaRuntime/LambdaHandlers.swift b/Sources/AWSLambdaRuntime/LambdaHandlers.swift index 0fe71fe9..f79c69b5 100644 --- a/Sources/AWSLambdaRuntime/LambdaHandlers.swift +++ b/Sources/AWSLambdaRuntime/LambdaHandlers.swift @@ -49,6 +49,7 @@ public protocol StreamingLambdaHandler: _Lambda_SendableMetatype { public protocol LambdaResponseStreamWriter { /// Write a response part into the stream. Bytes written are streamed continually. /// - Parameter buffer: The buffer to write. + /// - Parameter hasCustomHeaders: If `true`, the response will be sent with custom HTTP status code and headers. func write(_ buffer: ByteBuffer, hasCustomHeaders: Bool) async throws /// End the response stream and the underlying HTTP response. diff --git a/scripts/check-doc.sh b/scripts/check-doc.sh new file mode 100755 index 00000000..ba80f8a7 --- /dev/null +++ b/scripts/check-doc.sh @@ -0,0 +1,59 @@ +#!/bin/bash +##===----------------------------------------------------------------------===## +## +## This source file is part of the Swift.org open source project +## +## Copyright (c) 2024 Apple Inc. and the Swift project authors +## Licensed under Apache License v2.0 with Runtime Library Exception +## +## See https://swift.org/LICENSE.txt for license information +## See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +## +##===----------------------------------------------------------------------===## + +set -euo pipefail + +log() { printf -- "** %s\n" "$*" >&2; } +error() { printf -- "** ERROR: %s\n" "$*" >&2; } +fatal() { error "$@"; exit 1; } + +if [ ! -f .spi.yml ]; then + log "No '.spi.yml' found, no documentation targets to check." + exit 0 +fi + +if ! command -v yq &> /dev/null; then + fatal "yq could not be found. Please install yq to proceed." +fi + +package_files=$(find . -maxdepth 1 -name 'Package*.swift') +if [ -z "$package_files" ]; then + fatal "Package.swift not found. Please ensure you are running this script from the root of a Swift package." +fi + +# yq 3.1.0-3 doesn't have filter, otherwise we could replace the grep call with "filter(.identity == "swift-docc-plugin") | keys | .[]" +hasDoccPlugin=$(swift package dump-package | yq -r '.dependencies[].sourceControl' | grep -e "\"identity\": \"swift-docc-plugin\"" || true) +if [[ -n $hasDoccPlugin ]] +then + log "swift-docc-plugin already exists" +else + log "Appending swift-docc-plugin" + for package_file in $package_files; do + log "Editing $package_file..." + cat <> "$package_file" + +package.dependencies.append( + .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.0.0") +) +EOF + done +fi + +log "Checking documentation targets..." +for target in $(yq -r '.builder.configs[].documentation_targets[]' .spi.yml); do + log "Checking target $target..." + # shellcheck disable=SC2086 # We explicitly want to explode "$ADDITIONAL_DOCC_ARGUMENTS" into multiple arguments. + swift package plugin generate-documentation --target "$target" --warnings-as-errors --analyze $ADDITIONAL_DOCC_ARGUMENTS +done + +log "✅ Found no documentation issues." \ No newline at end of file From 6512c881e06e5b03812f15db2df9932feab698e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Stormacq?= Date: Fri, 25 Jul 2025 17:53:10 +0400 Subject: [PATCH 2/3] add items to gitignore --- .gitignore | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index b3b30ec1..3e1d4c2e 100644 --- a/.gitignore +++ b/.gitignore @@ -12,4 +12,6 @@ Package.resolved .vscode Makefile .devcontainer -.amazonq \ No newline at end of file +.amazonq +.kiro +nodejs \ No newline at end of file From 748c1fb5401ee4cf6bb23f7d51fdb0039a8d6743 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Stormacq?= Date: Fri, 25 Jul 2025 17:57:19 +0400 Subject: [PATCH 3/3] fix license header --- scripts/check-doc.sh | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/scripts/check-doc.sh b/scripts/check-doc.sh index ba80f8a7..ab27bd60 100755 --- a/scripts/check-doc.sh +++ b/scripts/check-doc.sh @@ -1,6 +1,19 @@ #!/bin/bash ##===----------------------------------------------------------------------===## ## +## This source file is part of the SwiftAWSLambdaRuntime open source project +## +## Copyright (c) 2025 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.org open source project ## ## Copyright (c) 2024 Apple Inc. and the Swift project authors