kotlin/services/{service}/
├── README.md                   # Generated service README
├── build.gradle.kts            # Gradle dependencies
└── {service}_metadata.yaml     # Metadata (in .doc_gen/metadata/)

cd .tools/readmes

# Create virtual environment
python -m venv .venv

# Activate environment (Linux/macOS)
source .venv/bin/activate

# Activate environment (Windows)
.venv\Scripts\activate

# Install dependencies
python -m pip install -r requirements_freeze.txt

# Generate README for specific service
python -m writeme --languages Kotlin:1 --services {service}

# {AWS Service} code examples for the SDK for Kotlin

## Overview

This is a workspace where you can find the following AWS SDK for Kotlin 
{AWS Service} examples.

## ⚠ Important

* Running this code might result in charges to your AWS account.
* Running the tests might result in charges to your AWS account.
* We recommend that you grant your code least privilege.

## Code examples

### Actions

The following examples show you how to perform actions using the AWS SDK for Kotlin.

* [Create a resource](src/main/kotlin/com/kotlin/{service}/{Service}Actions.kt#L123) (`CreateResource`)
* [Get a resource](src/main/kotlin/com/kotlin/{service}/{Service}Actions.kt#L456) (`GetResource`)

### Scenarios

The following examples show you how to implement common scenarios.

* [Get started with resources](src/main/kotlin/com/kotlin/{service}/{Service}Basics.kt) - Learn the basics by creating and managing resources.

### Hello

* [Hello {Service}](src/main/kotlin/com/kotlin/{service}/Hello{Service}.kt) - Get started with {AWS Service}.

## Prerequisites

- You must have an AWS account, and have your default credentials and AWS Region configured.
- Kotlin 1.9 or later
- Gradle 8.0 or later

## Install

To build and run the examples, navigate to the directory that contains a `build.gradle.kts` file and run the following command:

## Run the examples

### Instructions

All examples can be run individually. For example:

### Hello {Service}

This example shows you how to get started using {AWS Service}.

### Get started with {Service} resources

This interactive scenario runs at a command prompt and shows you how to use {AWS Service} to do the following:

1. Create a resource
2. Use the resource  
3. Clean up resources

## Run the tests

Unit tests in this module use JUnit 5 and MockK. To run all of the tests, 
run the following in your [GitHub root]/kotlin/services/{service} folder.

## Additional resources

- [{AWS Service} User Guide](https://docs.aws.amazon.com/{service}/latest/ug/)
- [{AWS Service} API Reference](https://docs.aws.amazon.com/{service}/latest/APIReference/)
- [AWS SDK for Kotlin ({AWS Service})](https://sdk.amazonaws.com/kotlin/api/latest/{service}/index.html)

# Check for metadata errors
python -m writeme --languages Kotlin:1 --services {service} --verbose

# Validate specific metadata file
python -c "import yaml; yaml.safe_load(open('.doc_gen/metadata/{service}_metadata.yaml'))"

# Check for missing snippet tags
grep -r "snippet-start" kotlin/services/{service}/

## Coroutines

This project uses Kotlin coroutines for asynchronous operations. All AWS SDK calls are suspend functions that should be called from within a coroutine scope.

```kotlin
suspend fun main() {
    // Your async code here
}

## Integration with CI/CD

### Automated README Validation
```bash
# In CI/CD pipeline, validate README is up-to-date
cd .tools/readmes
source .venv/bin/activate
python -m writeme --languages Kotlin:1 --services {service} --check

# Exit with error if README needs updates
if git diff --exit-code kotlin/services/{service}/README.md; then
    echo "README is up-to-date"
else
    echo "README needs to be regenerated"
    exit 1
fi

// In build.gradle.kts
tasks.register<Exec>("generateReadme") {
    group = "documentation"
    description = "Generate README using writeme tool"
    
    workingDir = file("../../.tools/readmes")
    commandLine = listOf(
        "python", "-m", "writeme",
        "--languages", "Kotlin:1",
        "--services", "{service}"
    )
}

tasks.named("build") {
    dependsOn("generateReadme")
}

### Async Operations

All AWS operations in this example are implemented as suspend functions:

```kotlin
suspend fun createResource(client: {Service}Client): String {
    // Implementation
}

### Extension Function Documentation
Document extension functions when used:
```markdown
### Extension Functions

This example includes extension functions for common operations:

```kotlin
fun List<Resource>.filterActive(): List<Resource> {
    return filter { it.status == ResourceStatus.Active }
}

### Null Safety Documentation
Highlight Kotlin's null safety features:
```markdown
### Null Safety

This example leverages Kotlin's null safety features:

```kotlin
val resource: Resource? = getResource(id)
resource?.let { 
    println("Resource found: ${it.name}")
}

This ensures documentation stays synchronized with code changes and maintains consistency across all Kotlin examples while highlighting Kotlin-specific features and patterns.