Change Rooms get/release parameter labels

[lawrence-forooghian]

rooms.get(named: "basketball") instead of rooms.get(name: "basketball")
rooms.release(named: "basketball") instead of rooms.release(name: "basketball")

in line with the fluency changes of #379, in particular the "Prefer method and function names that make use sites form grammatical English phrases" of https://www.swift.org/documentation/api-design-guidelines/

Thoughts?

withName: or forName: are also an option. I couldn't get an LLM to give me any useful answers; it kept telling me that everything I suggested was marvellous. There's UIImage(named name: String) in Apple's SDKs, for comparison.

Summary by CodeRabbit

• Refactor
  • Renamed Rooms API parameter label from name to named for get(...) and release(...). Update usage to chatClient.rooms.get(named: ...) and chatClient.rooms.release(named: ...). This is a breaking change requiring call-site updates.
• Documentation
  • Example app build command now specifies a required --platform flag (iOS, macOS, or tvOS).
  • Updated references to the new named: label across docs and examples.
• Tests
  • Adjusted test suites to use the renamed API labels without behavioral changes.

[coderabbitai]

Walkthrough

Renamed the Rooms API parameter label from name: to named: across public protocols, implementations, mocks, example app, and tests. Updated associated release methods to release(named:). Adjusted documentation to include a platform flag in the example build command.

Changes

Cohort / File(s)	Summary
Public API and Implementation Sources/AblyChat/Rooms.swift	Renamed methods: get(name:) → get(named:), get(name:options:) → get(named:options:), release(name:) → release(named:). Updated protocol, extension, and internal implementation signatures and docs accordingly.
Example App Example/AblyChatExample/ContentView.swift	Updated call site to use chatClient.rooms.get(named:options:).
Mocks Example/AblyChatExample/Mocks/MockClients.swift	Renamed MockRooms methods: get(name:options:) → get(named:options:), release(name:) → release(named:).
Tests Tests/AblyChatTests/ChatClientTests.swift, Tests/AblyChatTests/DefaultRoomsTests.swift, Tests/AblyChatTests/IntegrationTests.swift	Updated all uses of get(name:) and release(name:) to get(named:) and release(named:). No logic changes.
Documentation CLAUDE.md	Noted build command now includes --platform <platform> flag for example app.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I twitch my ears at named delights,
Rooms now called with clearer bites;
Hop-release, I name thee right—
Tests all pass in moonlit night.
Docs add platforms, flags in tow,
Thump-thump, onward APIs go.
(_/) ✨ (•_•) 🥕 />

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 52.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly describes the main change, renaming the Rooms API methods’ get and release parameter labels from name to named, which directly reflects the core changeset. It is concise, clear, and specific enough that someone reviewing history can immediately understand the intent. It avoids unnecessary detail or noise while focusing on the primary API update.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fluency-for-room-get-and-release

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 6be8bc6 and e5c84f0.

📒 Files selected for processing (7)

• CLAUDE.md (1 hunks)
• Example/AblyChatExample/ContentView.swift (1 hunks)
• Example/AblyChatExample/Mocks/MockClients.swift (2 hunks)
• Sources/AblyChat/Rooms.swift (4 hunks)
• Tests/AblyChatTests/ChatClientTests.swift (2 hunks)
• Tests/AblyChatTests/DefaultRoomsTests.swift (12 hunks)
• Tests/AblyChatTests/IntegrationTests.swift (5 hunks)

🧰 Additional context used

📓 Path-based instructions (3)

**/*.swift

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.swift: Expose SDK functionality via protocols; prefer associated types with opaque return types (some Protocol) over existentials (any Protocol)
Isolate all mutable state to the main actor; mark stateful objects with @mainactor
When using AsyncSequence operators in @mainactor contexts, mark operator closures as @sendable
Task, CheckedContinuation, and AsyncThrowingStream don’t support typed errors—use Result and call .get()
Dictionary.mapValues doesn’t support typed throws—use ablyChat_mapValuesWithTypedThrow extension
When the compiler struggles with typed throws, explicitly specify the error type with do throws(InternalError)
Specify the error type in closures, e.g., try items.map { jsonValue throws(InternalError) in … }

Files:

• Tests/AblyChatTests/ChatClientTests.swift
• Example/AblyChatExample/ContentView.swift
• Example/AblyChatExample/Mocks/MockClients.swift
• Sources/AblyChat/Rooms.swift
• Tests/AblyChatTests/DefaultRoomsTests.swift
• Tests/AblyChatTests/IntegrationTests.swift

Tests/**/*.swift

📄 CodeRabbit inference engine (CLAUDE.md)

Tests/**/*.swift: Use test attribution tags in tests: @SPEC, @specOneOf(m/n), @specPartial, @specUntested - , @specNotApplicable -
For Swift Testing #expect(throws:) with typed errors, move typed-throw code into a separate non-typed-throw function

Files:

• Tests/AblyChatTests/ChatClientTests.swift
• Tests/AblyChatTests/DefaultRoomsTests.swift
• Tests/AblyChatTests/IntegrationTests.swift

Sources/**/*.swift

📄 CodeRabbit inference engine (CLAUDE.md)

Sources/**/*.swift: Public API must use typed throws with ARTErrorInfo; use InternalError internally and convert at public API boundaries
Reference Chat SDK features spec items in code comments when implementing behavior (e.g., // @SPEC CHA-RL3g)
For public structs exposed by the API, provide an explicit public memberwise initializer
Test-only APIs in the library must be prefixed with testsOnly_ and wrapped in #if DEBUG

Files:

• Sources/AblyChat/Rooms.swift

🧬 Code graph analysis (6)

Tests/AblyChatTests/ChatClientTests.swift (3)

Example/AblyChatExample/ContentView.swift (1)

• room (89-91)

Example/AblyChatExample/Mocks/MockClients.swift (5)

• get (29-36)
• get (223-238)
• get (466-475)
• get (477-486)
• get (590-592)

Sources/AblyChat/Rooms.swift (2)

• get (60-63)
• get (164-271)

Example/AblyChatExample/ContentView.swift (3)

Example/AblyChatExample/Mocks/MockClients.swift (5)

• get (29-36)
• get (223-238)
• get (466-475)
• get (477-486)
• get (590-592)

Sources/AblyChat/Rooms.swift (2)

• get (60-63)
• get (164-271)

Sources/AblyChat/AblyCocoaExtensions/InternalAblyCocoaTypes.swift (3)

• get (223-239)
• get (241-257)
• get (437-440)

Example/AblyChatExample/Mocks/MockClients.swift (2)

Sources/AblyChat/Rooms.swift (3)

• get (60-63)
• get (164-271)
• release (325-363)

Sources/AblyChat/Room.swift (1)

• release (394-399)

Sources/AblyChat/Rooms.swift (3)

Example/AblyChatExample/Mocks/MockClients.swift (6)

• get (29-36)
• get (223-238)
• get (466-475)
• get (477-486)
• get (590-592)
• release (38-40)

Tests/AblyChatTests/DefaultRoomsTests.swift (1)

• release (395-428)

Tests/AblyChatTests/Mocks/MockRoom.swift (1)

• release (55-62)

Tests/AblyChatTests/DefaultRoomsTests.swift (3)

Example/AblyChatExample/Mocks/MockClients.swift (6)

• get (29-36)
• get (223-238)
• get (466-475)
• get (477-486)
• get (590-592)
• release (38-40)

Sources/AblyChat/Rooms.swift (3)

• get (60-63)
• get (164-271)
• release (325-363)

Example/AblyChatExample/ContentView.swift (1)

• room (89-91)

Tests/AblyChatTests/IntegrationTests.swift (3)

Example/AblyChatExample/Mocks/MockClients.swift (6)

• get (29-36)
• get (223-238)
• get (466-475)
• get (477-486)
• get (590-592)
• release (38-40)

Sources/AblyChat/Rooms.swift (3)

• get (60-63)
• get (164-271)
• release (325-363)

Tests/AblyChatTests/Mocks/MockChannels.swift (2)

• get (13-21)
• release (23-25)

🪛 LanguageTool

CLAUDE.md

[grammar] ~46-~46: There might be a mistake here.
Context: ...ld-example-app --platform ` - Build example app (platform: iOS, macOS, or t...

(QB_NEW_EN)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (10)

• GitHub Check: Xcode, iOS (Xcode 26.0)
• GitHub Check: Example app, tvOS (Xcode 26.0)
• GitHub Check: Example app, macOS (Xcode 26.0)
• GitHub Check: Xcode, release configuration, macOS (Xcode 26.0)
• GitHub Check: Xcode, release configuration, tvOS (Xcode 26.0)
• GitHub Check: Xcode, release configuration, iOS (Xcode 26.0)
• GitHub Check: Xcode, macOS (Xcode 26.0)
• GitHub Check: Xcode, tvOS (Xcode 26.0)
• GitHub Check: SPM (Xcode 26.0)
• GitHub Check: SPM, release configuration (Xcode 26.0)

🔇 Additional comments (11)

CLAUDE.md (1)

46-46: Documentation enhancement for build command.

The addition of the --platform <platform> parameter clarifies the available platform options (iOS, macOS, tvOS) for building the example app. This is helpful for developers.

Example/AblyChatExample/Mocks/MockClients.swift (1)

29-39: LGTM! Mock protocol conformance updated correctly.

The mock implementations now correctly conform to the updated Rooms protocol with the named: parameter label. The use of named name: for the external and internal labels follows Swift conventions and aligns with Apple's UIImage(named:) pattern.

Sources/AblyChat/Rooms.swift (3)

34-54: Excellent API fluency improvements!

The parameter label changes from name: to named: significantly improve the readability of the API. The method calls now read as natural English phrases:

• rooms.get(named: "basketball") ✓
• rooms.release(named: "basketball") ✓

This aligns perfectly with Apple's patterns (e.g., UIImage(named:)) and Swift API Design Guidelines.

---

60-62: Default implementation correctly delegates.

The convenience method properly calls through to the full signature with default options, maintaining the named: label consistency.

---

164-164: Internal implementations updated consistently.

Both internal methods correctly use named name: for the parameter, maintaining consistency between the public protocol and internal implementation.

Also applies to: 325-325

Tests/AblyChatTests/ChatClientTests.swift (1)

46-46: Test call sites updated correctly.

The test assertions now use the named: parameter label, maintaining test coverage while exercising the updated API.

Also applies to: 57-57

Tests/AblyChatTests/IntegrationTests.swift (2)

74-74: Integration test setup updated correctly.

The test initialization code now uses get(named: roomName, ...) which reads more naturally as "get a room named 'basketball'".

Also applies to: 82-82

---

508-508: Release and re-fetch operations updated.

The cleanup and verification sections of the tests correctly use both release(named:) and the subsequent get(named:) calls to verify room lifecycle behavior.

Also applies to: 517-517, 582-582

Example/AblyChatExample/ContentView.swift (1)

90-90: Example app demonstrates improved fluency.

The example app now showcases the more readable API: chatClient.rooms.get(named: roomName, ...) reads as a clear, grammatical English phrase. This provides an excellent reference for SDK users.

Tests/AblyChatTests/DefaultRoomsTests.swift (2)

49-49: Comprehensive test coverage updated.

The test suite thoroughly exercises the renamed API across various scenarios including:

• Room retrieval with and without options
• Room map entries and futures
• Option validation

All tests now use the named: label consistently.

Also applies to: 73-73, 99-102

---

293-293: Room release scenarios well-covered.

The release tests comprehensively validate the updated release(named:) API across different states:

• No room map entry
• Release in progress
• Pending get operations

The test coverage remains thorough with the API changes.

Also applies to: 313-321, 413-417

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[umair-ably]

rooms.get(named: "basketball") is defo nicer than rooms.get(name: "basketball")...

I say we go the full hog and align it with what Apple does with UIImage here... the user would still call rooms.get(named: "basketball") but the API is slightly more verbose (and cleaner) imo

[lawrence-forooghian]

I say we go the full hog and align it with what Apple does with UIImage here

isn't that what this PR is proposing? func get(named name: String, options: RoomOptions) is the full signature

[maratal]

I agree with the name.