1================================================
2API Notes: Annotations Without Modifying Headers
3================================================
4
5**The Problem:** You have headers you want to use, but you also want to add
6extra information to the API. You don't want to put that information in the
7headers themselves --- perhaps because you want to keep them clean for other
8clients, or perhaps because they're from some open source project and you don't
9want to modify them at all.
10
11**Incomplete solution:** Redeclare all the interesting parts of the API in your
12own header and add the attributes you want. Unfortunately, this:
13
14* doesn't work with attributes that must be present on a definition
15* doesn't allow changing the definition in other ways
16* requires your header to be included in any client code to take effect
17
18**Better solution:** Provide a "sidecar" file with the information you want to
19add, and have that automatically get picked up by the module-building logic in
20the compiler.
21
22That's API notes.
23
24API notes use a YAML-based file format. YAML is a format best explained by
25example, so here is a `small example`__ from the compiler test suite of API
26notes for a hypothetical "SomeKit" framework.
27
28__ test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKit.apinotes
29
30
31Usage
32=====
33
34API notes files are found relative to the module map that defines a module,
35under the name "SomeKit.apinotes" for a module named "SomeKit". Additionally, a
36file named "SomeKit_private.apinotes" will also be picked up to go with a
37private module map. For bare modules these two files will be in the same
38directory as the corresponding module map; for framework modules, they should
39be placed in the Headers and PrivateHeaders directories, respectively. The
40module map for a private top-level framework module should be placed in the
41PrivateHeaders directory as well, though it does not need an additional
42"_private" suffix on its name.
43
44Clang will search for API notes files next to module maps only when passed the
45``-fapi-notes-modules`` option.
46
47
48Limitations
49===========
50
51- Since they're identified by module name, API notes cannot be used to modify
52  arbitrary textual headers.
53
54
55"Versioned" API Notes
56=====================
57
58Many API notes affect how a C API is imported into Swift. In order to change
59that behavior while still remaining backwards-compatible, API notes can be
60selectively applied based on the Swift compatibility version provided to the
61compiler (e.g. ``-fapi-notes-swift-version=5``). The rule is that an
62explicitly-versioned API note applies to that version *and all earlier
63versions,* and any applicable explicitly-versioned API note takes precedence
64over an unversioned API note.
65
66
67Reference
68=========
69
70An API notes file contains a YAML dictionary with the following top-level
71entries:
72
73:Name:
74
75  The name of the module (the framework name, for frameworks). Note that this
76  is always the name of a top-level module, even within a private API notes
77  file.
78
79  ::
80
81    Name: MyFramework
82
83:Classes, Protocols, Tags, Typedefs, Globals, Enumerators, Functions:
84
85  Arrays of top-level declarations. Each entry in the array must have a
86  'Name' key with its Objective-C name. "Tags" refers to structs, enums, and
87  unions; "Enumerators" refers to enum cases.
88
89  ::
90
91    Classes:
92    - Name: MyController
93      …
94    - Name: MyView
95      …
96
97:SwiftVersions:
98
99  Contains explicit information for backwards compatibility. Each entry in
100  the array contains a 'Version' key, which should be set to '4' for
101  annotations that only apply to Swift 4 mode and earlier. The other entries
102  in this dictionary are the same declaration entries as at the top level:
103  Classes, Protocols, Tags, Typedefs, Globals, Enumerators, and Functions.
104
105  ::
106
107    SwiftVersions:
108    - Version: 4
109      Classes: …
110      Protocols: …
111
112Each entry under 'Classes' and 'Protocols' can contain "Methods" and
113"Properties" arrays, in addition to the attributes described below:
114
115:Methods:
116
117  Identified by 'Selector' and 'MethodKind'; the MethodKind is either
118  "Instance" or "Class".
119
120  ::
121
122    Classes:
123    - Name: UIViewController
124      Methods:
125      - Selector: "presentViewController:animated:"
126        MethodKind: Instance
127        …
128
129:Properties:
130
131  Identified by 'Name' and 'PropertyKind'; the PropertyKind is also either
132  "Instance" or "Class".
133
134  ::
135
136    Classes:
137    - Name: UIView
138      Properties:
139      - Name: subviews
140        PropertyKind: Instance
141        …
142
143Each declaration supports the following annotations (if relevant to that
144declaration kind), all of which are optional:
145
146:SwiftName:
147
148  Equivalent to ``NS_SWIFT_NAME``. For a method, must include the full Swift name
149  with all arguments. Use "_" to omit an argument label.
150
151  ::
152
153    - Selector: "presentViewController:animated:"
154      MethodKind: Instance
155      SwiftName: "present(_:animated:)"
156
157    - Class: NSBundle
158      SwiftName: Bundle
159
160:Availability, AvailabilityMsg:
161
162  A value of "nonswift" is equivalent to ``NS_SWIFT_UNAVAILABLE``. A value of
163  "available" can be used in the "SwiftVersions" section to undo the effect of
164  "nonswift".
165
166  ::
167
168    - Selector: "dealloc"
169      MethodKind: Instance
170      Availability: nonswift
171      AvailabilityMsg: "prefer 'deinit'"
172
173:SwiftPrivate:
174
175  Equivalent to NS_REFINED_FOR_SWIFT.
176
177  ::
178
179    - Name: CGColorEqualToColor
180      SwiftPrivate: true
181
182:Nullability:
183
184  Used for properties and globals. There are four options, identified by their
185  initials:
186
187  - ``Nonnull`` or ``N`` (corresponding to ``_Nonnull``)
188  - ``Optional`` or ``O`` (corresponding to ``_Nullable``)
189  - ``Unspecified`` or ``U`` (corresponding to ``_Null_unspecified``)
190  - ``Scalar`` or ``S`` (deprecated)
191
192  Note that 'Nullability' is overridden by 'Type', even in a "SwiftVersions"
193  section.
194
195  .. note::
196
197    'Nullability' can also be used to describe the argument types of methods
198    and functions, but this usage is deprecated in favor of 'Parameters' (see
199    below).
200
201  ::
202
203    - Name: dataSource
204      Nullability: O
205
206:NullabilityOfRet:
207
208  Used for methods and functions. Describes the nullability of the return type.
209
210  Note that 'NullabilityOfRet' is overridden by 'ResultType', even in a
211  "SwiftVersions" section.
212
213  .. warning::
214
215    Due to a compiler bug, 'NullabilityOfRet' may change nullability of the
216    parameters as well (rdar://30544062). Avoid using it and instead use
217    'ResultType' and specify the return type along with a nullability
218    annotation (see documentation for 'ResultType').
219
220  ::
221
222    - Selector: superclass
223      MethodKind: Class
224      NullabilityOfRet: O
225
226:Type:
227
228  Used for properties and globals. This completely overrides the type of the
229  declaration; it should ideally only be used for Swift backwards
230  compatibility, when existing type information has been made more precise in a
231  header. Prefer 'Nullability' and other annotations when possible.
232
233  We parse the specified type as if it appeared at the location of the
234  declaration whose type is being modified.  Macros are not available and
235  nullability must be applied explicitly (even in an ``NS_ASSUME_NONNULL_BEGIN``
236  section).
237
238  ::
239
240    - Name: delegate
241      PropertyKind: Instance
242      Type: "id"
243
244:ResultType:
245
246  Used for methods and functions. This completely overrides the return type; it
247  should ideally only be used for Swift backwards compatibility, when existing
248  type information has been made more precise in a header.
249
250  We parse the specified type as if it appeared at the location of the
251  declaration whose type is being modified.  Macros are not available and
252  nullability must be applied explicitly (even in an ``NS_ASSUME_NONNULL_BEGIN``
253  section).
254
255  ::
256
257    - Selector: "subviews"
258      MethodKind: Instance
259      ResultType: "NSArray * _Nonnull"
260
261:SwiftImportAsAccessors:
262
263  Used for properties. If true, the property will be exposed in Swift as its
264  accessor methods, rather than as a computed property using ``var``.
265
266  ::
267
268    - Name: currentContext
269      PropertyKind: Class
270      SwiftImportAsAccessors: true
271
272:NSErrorDomain:
273
274  Used for ``NSError`` code enums. The value is the name of the associated
275  domain ``NSString`` constant; an empty string (``""``) means the enum is a
276  normal enum rather than an error code.
277
278  ::
279
280    - Name: MKErrorCode
281      NSErrorDomain: MKErrorDomain
282
283:SwiftWrapper:
284
285  Controls ``NS_STRING_ENUM`` and ``NS_EXTENSIBLE_STRING_ENUM``. There are three
286  options:
287
288  - "struct" (extensible)
289  - "enum"
290  - "none"
291
292  Note that even an "enum" wrapper is still presented as a struct in Swift;
293  it's just a "more enum-like" struct.
294
295  ::
296
297    - Name: AVMediaType
298      SwiftWrapper: none
299
300:EnumKind:
301
302  Has the same effect as ``NS_ENUM`` and ``NS_OPTIONS``. There are four options:
303
304  - "NSEnum" / "CFEnum"
305  - "NSClosedEnum" / "CFClosedEnum"
306  - "NSOptions" / "CFOptions"
307  - "none"
308
309  ::
310
311    - Name: GKPhotoSize
312      EnumKind: none
313
314:Parameters:
315
316  Used for methods and functions. Parameters are identified by a 0-based
317  'Position' and support the 'Nullability', 'NoEscape', and 'Type' keys.
318
319  .. note::
320
321    Using 'Parameters' within a parameter entry to describe the parameters of a
322    block is not implemented. Use 'Type' on the entire parameter instead.
323
324  ::
325
326    - Selector: "isEqual:"
327      MethodKind: Instance
328      Parameters:
329      - Position: 0
330        Nullability: O
331
332:NoEscape:
333
334  Used only for block parameters. Equivalent to ``NS_NOESCAPE``.
335
336  ::
337
338    - Name: dispatch_sync
339      Parameters:
340      - Position: 0
341        NoEscape: true
342
343:SwiftBridge:
344
345  Used for Objective-C class types bridged to Swift value types. An empty
346  string ("") means a type is not bridged. Not supported outside of Apple
347  frameworks (the Swift side of it requires conforming to implementation-detail
348  protocols that are subject to change).
349
350  ::
351
352    - Name: NSIndexSet
353      SwiftBridge: IndexSet
354
355:DesignatedInit:
356
357  Used for init methods. Equivalent to ``NS_DESIGNATED_INITIALIZER``.
358
359  ::
360
361    - Selector: "initWithFrame:"
362      MethodKind: Instance
363      DesignatedInit: true
364