aboutsummaryrefslogtreecommitdiff
path: root/clang/docs/APINotes.rst
blob: a6e200e8bffde86315b60ce330c4bb99cc3081bd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
================================================
API Notes: Annotations Without Modifying Headers
================================================

**The Problem:** You have headers you want to use, but you also want to add
extra information to the API. You don't want to put that information in the
headers themselves --- perhaps because you want to keep them clean for other
clients, or perhaps because they're from some open source project and you don't
want to modify them at all.

**Incomplete solution:** Redeclare all the interesting parts of the API in your
own header and add the attributes you want. Unfortunately, this:

* doesn't work with attributes that must be present on a definition
* doesn't allow changing the definition in other ways
* requires your header to be included in any client code to take effect

**Better solution:** Provide a "sidecar" file with the information you want to
add, and have that automatically get picked up by the module-building logic in
the compiler.

That's API notes.

API notes use a YAML-based file format. YAML is a format best explained by
example, so here is a `small example
<https://github.com/llvm/llvm-project/blob/main/clang/test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKit.apinotes>`_
from the compiler test suite of API
notes for a hypothetical "SomeKit" framework.


Usage
=====

API notes files are found relative to the module map that defines a module,
under the name "SomeKit.apinotes" for a module named "SomeKit". Additionally, a
file named "SomeKit_private.apinotes" will also be picked up to go with a
private module map. For bare modules these two files will be in the same
directory as the corresponding module map; for framework modules, they should
be placed in the Headers and PrivateHeaders directories, respectively. The
module map for a private top-level framework module should be placed in the
PrivateHeaders directory as well, though it does not need an additional
"_private" suffix on its name.

Clang will search for API notes files next to module maps only when passed the
``-fapi-notes-modules`` option.


Limitations
===========

- Since they're identified by module name, API notes cannot be used to modify
  arbitrary textual headers.


"Versioned" API Notes
=====================

Many API notes affect how a C API is imported into Swift. In order to change
that behavior while still remaining backwards-compatible, API notes can be
selectively applied based on the Swift compatibility version provided to the
compiler (e.g. ``-fapi-notes-swift-version=5``). The rule is that an
explicitly-versioned API note applies to that version *and all earlier
versions,* and any applicable explicitly-versioned API note takes precedence
over an unversioned API note.


Reference
=========

An API notes file contains a YAML dictionary with the following top-level
entries:

:Name:

  The name of the module (the framework name, for frameworks). Note that this
  is always the name of a top-level module, even within a private API notes
  file.

  ::

    Name: MyFramework

:Classes, Protocols, Tags, Typedefs, Globals, Enumerators, Functions:

  Arrays of top-level declarations. Each entry in the array must have a
  'Name' key with its Objective-C name. "Tags" refers to structs, enums, and
  unions; "Enumerators" refers to enum cases.

  ::

    Classes:
    - Name: MyController
      …
    - Name: MyView
      …

:SwiftVersions:

  Contains explicit information for backwards compatibility. Each entry in
  the array contains a 'Version' key, which should be set to '4' for
  annotations that only apply to Swift 4 mode and earlier. The other entries
  in this dictionary are the same declaration entries as at the top level:
  Classes, Protocols, Tags, Typedefs, Globals, Enumerators, and Functions.

  ::

    SwiftVersions:
    - Version: 4
      Classes: …
      Protocols: …

Each entry under 'Classes' and 'Protocols' can contain "Methods" and
"Properties" arrays, in addition to the attributes described below:

:Methods:

  Identified by 'Selector' and 'MethodKind'; the MethodKind is either
  "Instance" or "Class".

  ::

    Classes:
    - Name: UIViewController
      Methods:
      - Selector: "presentViewController:animated:"
        MethodKind: Instance
        …

:Properties:

  Identified by 'Name' and 'PropertyKind'; the PropertyKind is also either
  "Instance" or "Class".

  ::

    Classes:
    - Name: UIView
      Properties:
      - Name: subviews
        PropertyKind: Instance
        …

Each declaration supports the following annotations (if relevant to that
declaration kind), all of which are optional:

:SwiftName:

  Equivalent to ``NS_SWIFT_NAME``. For a method, must include the full Swift name
  with all arguments. Use "_" to omit an argument label.

  ::

    - Selector: "presentViewController:animated:"
      MethodKind: Instance
      SwiftName: "present(_:animated:)"

    - Class: NSBundle
      SwiftName: Bundle

:Availability, AvailabilityMsg:

  A value of "nonswift" is equivalent to ``NS_SWIFT_UNAVAILABLE``. A value of
  "available" can be used in the "SwiftVersions" section to undo the effect of
  "nonswift".

  ::

    - Selector: "dealloc"
      MethodKind: Instance
      Availability: nonswift
      AvailabilityMsg: "prefer 'deinit'"

:SwiftPrivate:

  Equivalent to NS_REFINED_FOR_SWIFT.

  ::

    - Name: CGColorEqualToColor
      SwiftPrivate: true

:Nullability:

  Used for properties and globals. There are four options, identified by their
  initials:

  - ``Nonnull`` or ``N`` (corresponding to ``_Nonnull``)
  - ``Optional`` or ``O`` (corresponding to ``_Nullable``)
  - ``Unspecified`` or ``U`` (corresponding to ``_Null_unspecified``)
  - ``Scalar`` or ``S`` (deprecated)

  Note that 'Nullability' is overridden by 'Type', even in a "SwiftVersions"
  section.

  .. note::

    'Nullability' can also be used to describe the argument types of methods
    and functions, but this usage is deprecated in favor of 'Parameters' (see
    below).

  ::

    - Name: dataSource
      Nullability: O

:NullabilityOfRet:

  Used for methods and functions. Describes the nullability of the return type.

  Note that 'NullabilityOfRet' is overridden by 'ResultType', even in a
  "SwiftVersions" section.

  .. warning::

    Due to a compiler bug, 'NullabilityOfRet' may change nullability of the
    parameters as well (rdar://30544062). Avoid using it and instead use
    'ResultType' and specify the return type along with a nullability
    annotation (see documentation for 'ResultType').

  ::

    - Selector: superclass
      MethodKind: Class
      NullabilityOfRet: O

:Type:

  Used for properties and globals. This completely overrides the type of the
  declaration; it should ideally only be used for Swift backwards
  compatibility, when existing type information has been made more precise in a
  header. Prefer 'Nullability' and other annotations when possible.

  We parse the specified type as if it appeared at the location of the
  declaration whose type is being modified.  Macros are not available and
  nullability must be applied explicitly (even in an ``NS_ASSUME_NONNULL_BEGIN``
  section).

  ::

    - Name: delegate
      PropertyKind: Instance
      Type: "id"

:ResultType:

  Used for methods and functions. This completely overrides the return type; it
  should ideally only be used for Swift backwards compatibility, when existing
  type information has been made more precise in a header.

  We parse the specified type as if it appeared at the location of the
  declaration whose type is being modified.  Macros are not available and
  nullability must be applied explicitly (even in an ``NS_ASSUME_NONNULL_BEGIN``
  section).

  ::

    - Selector: "subviews"
      MethodKind: Instance
      ResultType: "NSArray * _Nonnull"

:SwiftImportAsAccessors:

  Used for properties. If true, the property will be exposed in Swift as its
  accessor methods, rather than as a computed property using ``var``.

  ::

    - Name: currentContext
      PropertyKind: Class
      SwiftImportAsAccessors: true

:NSErrorDomain:

  Used for ``NSError`` code enums. The value is the name of the associated
  domain ``NSString`` constant; an empty string (``""``) means the enum is a
  normal enum rather than an error code.

  ::

    - Name: MKErrorCode
      NSErrorDomain: MKErrorDomain

:SwiftWrapper:

  Controls ``NS_STRING_ENUM`` and ``NS_EXTENSIBLE_STRING_ENUM``. There are three
  options:

  - "struct" (extensible)
  - "enum"
  - "none"

  Note that even an "enum" wrapper is still presented as a struct in Swift;
  it's just a "more enum-like" struct.

  ::

    - Name: AVMediaType
      SwiftWrapper: none

:EnumKind:

  Has the same effect as ``NS_ENUM`` and ``NS_OPTIONS``. There are four options:

  - "NSEnum" / "CFEnum"
  - "NSClosedEnum" / "CFClosedEnum"
  - "NSOptions" / "CFOptions"
  - "none"

  ::

    - Name: GKPhotoSize
      EnumKind: none

:Parameters:

  Used for methods and functions. Parameters are identified by a 0-based
  'Position' and support the 'Nullability', 'NoEscape', and 'Type' keys.

  .. note::

    Using 'Parameters' within a parameter entry to describe the parameters of a
    block is not implemented. Use 'Type' on the entire parameter instead.

  ::

    - Selector: "isEqual:"
      MethodKind: Instance
      Parameters:
      - Position: 0
        Nullability: O

:NoEscape:

  Used only for block parameters. Equivalent to ``NS_NOESCAPE``.

  ::

    - Name: dispatch_sync
      Parameters:
      - Position: 0
        NoEscape: true

:SwiftBridge:

  Used for Objective-C class types bridged to Swift value types. An empty
  string ("") means a type is not bridged. Not supported outside of Apple
  frameworks (the Swift side of it requires conforming to implementation-detail
  protocols that are subject to change).

  ::

    - Name: NSIndexSet
      SwiftBridge: IndexSet

:DesignatedInit:

  Used for init methods. Equivalent to ``NS_DESIGNATED_INITIALIZER``.

  ::

    - Selector: "initWithFrame:"
      MethodKind: Instance
      DesignatedInit: true