clang/docs/APINotes.rst

   1 ================================================
   2 API Notes: Annotations Without Modifying Headers
   3 ================================================
   4
   5 **The Problem:** You have headers you want to use, but you also want to add
   6 extra information to the API. You don't want to put that information in the
   7 headers themselves --- perhaps because you want to keep them clean for other
   8 clients, or perhaps because they're from some open source project and you don't
   9 want to modify them at all.
  10
  11 **Incomplete solution:** Redeclare all the interesting parts of the API in your
  12 own 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
  19 add, and have that automatically get picked up by the module-building logic in
  20 the compiler.
  21
  22 That's API notes.
  23
  24 API notes use a YAML-based file format. YAML is a format best explained by
  25 example, so here is a `small example`__ from the compiler test suite of API
  26 notes for a hypothetical "SomeKit" framework.
  27
  28 __ test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKit.apinotes
  29
  30
  31 Usage
  32 =====
  33
  34 API notes files are found relative to the module map that defines a module,
  35 under the name "SomeKit.apinotes" for a module named "SomeKit". Additionally, a
  36 file named "SomeKit_private.apinotes" will also be picked up to go with a
  37 private module map. For bare modules these two files will be in the same
  38 directory as the corresponding module map; for framework modules, they should
  39 be placed in the Headers and PrivateHeaders directories, respectively. The
  40 module map for a private top-level framework module should be placed in the
  41 PrivateHeaders directory as well, though it does not need an additional
  42 "_private" suffix on its name.
  43
  44 Clang will search for API notes files next to module maps only when passed the
  45 ``-fapi-notes-modules`` option.
  46
  47
  48 Limitations
  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
  58 Many API notes affect how a C API is imported into Swift. In order to change
  59 that behavior while still remaining backwards-compatible, API notes can be
  60 selectively applied based on the Swift compatibility version provided to the
  61 compiler (e.g. ``-fapi-notes-swift-version=5``). The rule is that an
  62 explicitly-versioned API note applies to that version *and all earlier
  63 versions,* and any applicable explicitly-versioned API note takes precedence
  64 over an unversioned API note.
  65
  66
  67 Reference
  68 =========
  69
  70 An API notes file contains a YAML dictionary with the following top-level
  71 entries:
  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
 112 Each 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
 143 Each declaration supports the following annotations (if relevant to that
 144 declaration 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