Skip to content

Commit f7ab2d4

Browse files
authored
[Docs] Follow-up to #14325 (#14326)
1 parent b4d37ee commit f7ab2d4

File tree

1 file changed

+12
-12
lines changed

1 file changed

+12
-12
lines changed

docs/firebase-api-guidelines.md

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@ process.
88
If Objective-C is required, additionally refer to the [Google Objective-C Style
99
Guide][3].
1010

11-
## Guidance {:#guidance}
11+
## Guidance
1212

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

1515
Swift is the preferred language for Apple development, so new Firebase APIs
1616
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
2424
idiomatic. Apple provides a [guide][4] for improving such Objective-C API
2525
declarations for Swift.
2626

27-
### Include Swift code samples {:#include-swift}
27+
### Include Swift code samples
2828

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

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

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

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

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

57-
### API Availability {:#api-availability}
57+
### API Availability
5858

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

84-
### Constants {:#constants}
84+
### Constants
8585

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

98-
### Minimizing optionals {:#minimizing-optionals}
98+
### Minimizing optionals
9999

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

144-
### Documentation {:#documentation}
144+
### Documentation
145145

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

150-
### Naming Conventions {:#naming-conventions}
150+
### Naming Conventions
151151

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

170-
### Errors {:#errors}
170+
### Errors
171171

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

177-
### Don't define typedefs {:#don't-define}
177+
### Don't define typedefs
178178

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

0 commit comments

Comments
 (0)