Swift Api Design Guidelines Skill

# Argument Labels

## Omit Labels Only When It Is Still Clear
- Omit all labels only when unlabeled arguments cannot be usefully distinguished.

Examples:
- `min(x, y)`
- `zip(a, b)`

## Value-Preserving Conversion Initializers
- Omit the first argument label for value-preserving conversions.
- The first argument should be the conversion source.

```swift
let value = Int64(someUInt32)
```

## Prepositional Phrase Rule
- If the first argument is part of a prepositional phrase, usually include the label beginning with the preposition.

```swift
x.removeBoxes(havingLength: 12)
```

Exception:
- When first arguments are parts of one abstraction, move the label boundary after the preposition.

```swift
a.moveTo(x: b, y: c)
a.fadeFrom(red: b, green: c, blue: d)
```

## Grammatical Phrase Rule
- If the first argument forms part of a grammatical phrase, omit its label and move leading words into the base name.

```swift
x.addSubview(y)
```

## Label Everything Else
- If the first argument is not part of a grammatical phrase, label it.
- Label all remaining arguments unless a specific rule justifies omission.

```swift
view.dismiss(animated: false)
words.split(maxSplits: 12)
students.sorted(isOrderedBefore: Student.namePrecedes)
```


# Fundamentals

## Core Priorities
- Clarity at the point of use is the most important design goal.
- Clarity is more important than brevity.
- Evaluate declarations in real call-site context, not in isolation.

## Documentation Is Part Of API Design
- Write a documentation comment for every declaration.
- If the API is hard to describe simply, redesign may be needed.
- Use Swift Markdown and recognized symbol markup.

## Summary Writing Rules
- Start with a summary that can stand on its own.
- Prefer a single sentence fragment ending in a period.
- Describe:
  - Functions/methods: what they do and return.
  - Subscripts: what they access.
  - Initializers: what they create.
  - Other declarations: what they are.

## Suggested Structure
```swift
/// Returns a "view" of `self` containing the same elements in
/// reverse order.
func reversed() -> ReverseCollection
```

```swift
/// Accesses the `index`th element.
subscript(index: Int) -> Element { get set }
```

```swift
/// Creates an instance containing `n` repetitions of `x`.
init(count n: Int, repeatedElement x: Element)
```

## Additional Comment Content
- Add extra paragraphs only when they improve comprehension.
- Use symbol markup bullets when relevant, such as:
  - `Parameter` / `Parameters`
  - `Returns`
  - `Throws`
  - `Note`
  - `Warning`
  - `SeeAlso`

## Practical Check
- Read a use-site snippet and confirm the intent is obvious without external explanation.


# General Conventions

## Document Computed Property Complexity
- If a computed property is not `O(1)`, document its complexity.
- Many readers assume property access is cheap unless told otherwise.

## Prefer Methods/Properties To Free Functions
Use free functions only when:
1. There is no obvious `self`.
2. The function is an unconstrained generic.
3. Function syntax is established domain notation.

## Follow Swift Casing
- Types/protocols: `UpperCamelCase`.
- Other declarations: `lowerCamelCase`.
- Acronyms and initialisms should be cased consistently with style conventions.

```swift
var utf8Bytes: [UTF8.CodeUnit]
var isRepresentableAsASCII = true
var radarDetector: RadarScanner
```

## Overloads
- Methods may share base names when meaning is the same or domains are distinct.
- Do not reuse a base name for semantically different operations.
- Avoid overloading on return type alone; type inference can make calls ambiguous.

## Review Heuristic
- Check that overload sets are readable, semantically coherent, and unambiguous at call sites.


# Parameters

## Choose Names For Documentation Quality
- Parameter names do not appear at most call sites, but they drive documentation clarity.
- Select names that read naturally in summaries and parameter descriptions.

```swift
/// Returns the e