Skip to content

Commit

Permalink
[Docs] Follow-up to #14325 (#14326)
Browse files Browse the repository at this point in the history
  • Loading branch information
ncooke3 authored Jan 9, 2025
1 parent b4d37ee commit f7ab2d4
Showing 1 changed file with 12 additions and 12 deletions.
24 changes: 12 additions & 12 deletions docs/firebase-api-guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ process.
If Objective-C is required, additionally refer to the [Google Objective-C Style
Guide][3].

## Guidance {:#guidance}
## Guidance

### New APIs should be Swift-only {:#new-apis}
### New APIs should be Swift-only

Swift is the preferred language for Apple development, so new Firebase APIs
should be fully optimized for Swift. When designing new APIs, consider whether
Expand All @@ -24,13 +24,13 @@ corresponding generated Swift interface should be manually refined to be more
idiomatic. Apple provides a [guide][4] for improving such Objective-C API
declarations for Swift.

### Include Swift code samples {:#include-swift}
### Include Swift code samples

It is important for new APIs to be as easy to use in Swift as possible. When
creating a proposal, prioritize Swift code samples to demonstrate the new API's
usage.

### Async API should be written in async/await form {:#async-api}
### Async API should be written in async/await form

Swift has built-in [support][5] for writing asynchronous code. If a
callback-based API is required, it should be carefully considered and justified.
Expand All @@ -45,7 +45,7 @@ public func fetchData() async throws -> Data { ... }
public func fetchData(completion: (Data, any Error) -> Void) { ... }
```

### New APIs should be Sendable {:#new-apis}
### New APIs should be Sendable

A [Sendable][7] type is one that is thread-safe and can be shared safely across
multiple concurrency contexts. The requirements for conforming to the Sendable
Expand All @@ -54,7 +54,7 @@ introduces strict concurrency checking and enforces Sendable types in
asynchronous code. If applicable, new APIs should be Sendable and designed to be
used in an async context (e.g. `Task`).

### API Availability {:#api-availability}
### API Availability

By design, an API may not be available on a given Apple platform. Swift supports
platform-specific compilation and runtime checks.
Expand All @@ -81,7 +81,7 @@ product's CocoaPods podspec, and declare it on the API's signature via the
func myNewAPI() { ... }
```

### Constants {:#constants}
### Constants

In Objective-C, constants were usually defined at the global level. In Swift,
constants can instead be grouped under a case-less enum. The benefit of a
Expand All @@ -95,7 +95,7 @@ public enum NetworkConstants {
}
```

### Minimizing optionals {:#minimizing-optionals}
### Minimizing optionals

Unlike Objective-C, Swift handles nullability in a type safe way using
[optionals][10]. While useful, avoid overusing them as they can complicate
Expand Down Expand Up @@ -141,13 +141,13 @@ public struct CustomValue {
func setValues(_ values: [String: CustomValue]) async throws { ... }
```

### Documentation {:#documentation}
### Documentation

New APIs should have corresponding documentation using [Swift-flavored
Markdown][13]. Xcode can generate a documentation block's structure when the
cursor is in the method signature and ⌥ ⌘ / is pressed.

### Naming Conventions {:#naming-conventions}
### Naming Conventions

[Swift's official API design guidelines][1] provide an overview to creating
idiomatic Swift API.
Expand All @@ -167,14 +167,14 @@ Consider the precedent set by the existing API that is adjacent to the new API
being added. New APIs should be consistent with the existing Firebase API
surface, and diverge only when justified.

### Errors {:#errors}
### Errors

If the new API can fail, mark the API as `throws` and create (or add onto) an
existing public [error][15] for the API to throw. Swift provides an `Error`
protocol that can be used to create descriptive errors that can be easily
handled by clients.

### Don't define typedefs {:#don't-define}
### Don't define typedefs

_This guideline only applies when changing public Objective-C API_.

Expand Down

0 comments on commit f7ab2d4

Please sign in to comment.