basecamp / basecamp/basecamp-sdk

Generated Swift service methods carry no documentation at all

Open
#569 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
49
Forks
12
Avg merge
20h 47m
Merged PRs (30d)
89

Description

## What

The Swift generator emits no method-level documentation for generated service methods — no summary line, no `- Parameter` entries for path parameters, and none for required query parameters.

```
$ rg -c '\- Parameter' swift/Sources/Basecamp/Generated/Services/*.swift
(no matches)
```

That holds on `main` and has since the generator was written. The only `///` lines in the generated Swift tree are property docs on options structs and the `Deprecated:` leader that #406 added.

For comparison, `ListRecordingOptions` and `RecordingsService.list` on `main`:

```swift
public struct ListRecordingOptions: Sendable {
public var bucket: String?
...
}

public final class RecordingsService: BaseService, @unchecked Sendable {
public func get(recordingId: Int) async throws -> Recording {
```

Xcode QuickHelp therefore shows nothing for any generated Swift method, while Go, TypeScript, Ruby and Kotlin all surface the OpenAPI descriptions.

## Why it is filed separately

Raised as a review finding on #561, which added per-*property* KDoc/doc-comments to Kotlin and Swift options structs — the place optional query parameters live. #561 did not regress required-parameter documentation, because there was none to regress, and closing the real gap means emitting summaries and `- Parameter` lines for every method: a generator change with its own six-tree diff and its own drift proof.

## Scope

- `swift/Sources/BasecampGenerator/ServiceEmitter.swift`: emit `///` summary from the operation description, `- Parameter` lines for path parameters, required query parameters, and body/upload parameters.
- Mirror the escaping already used for options-struct property docs (collapse spec line wrapping; leave deprecation notices to the existing `Deprecated:` leader so `scripts/check-deprecation-parity` stays satisfied).
- Regenerate; the Swift drift gate from #444 covers freshness.

Contributor guide

Open the contributing guide

Research direction

Start in swift/Sources/BasecampGenerator/ServiceEmitter.swift and compare the existing escaping for options-struct property docs with the operation descriptions and parameters available to the emitter. Regenerate the Swift tree, then run the Swift drift gate from #444 and scripts/check-deprecation-parity. Done means generated methods have summaries and - Parameter lines for the specified parameters without breaking deprecation parity.

Written by the indexing model from the issue text.

Assessment

Tech stack
swift
Domain
documentation, tooling
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.