diff --git a/docs/firebase-api-guidelines.md b/docs/firebase-api-guidelines.md index 662978f8c90..4c8735c44e0 100644 --- a/docs/firebase-api-guidelines.md +++ b/docs/firebase-api-guidelines.md @@ -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 @@ -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. @@ -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 @@ -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. @@ -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 @@ -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 @@ -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. @@ -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_.