basecamp / basecamp/basecamp-sdk
Generated Swift service methods carry no documentation at all
- 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
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