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
  26 <https://github.com/llvm/llvm-project/blob/main/clang/test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKit.apinotes>`_
  27 from the compiler test suite of API
  28 notes for a hypothetical "SomeKit" framework.
  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, Namespaces:
  84
  85   Arrays of top-level declarations. Each entry in the array must have a
  86   'Name' key with its Objective-C or C++ name. "Tags" refers to structs,
  87   C++ classes, enums, and unions; "Classes" refers to Objective-C classes;
  88   "Enumerators" refers to enum cases.
  89
  90   ::
  91
  92     Classes:
  93     - Name: MyController
  94       …
  95     - Name: MyView
  96       …
  97
  98 :SwiftVersions:
  99
 100   Contains explicit information for backwards compatibility. Each entry in
 101   the array contains a 'Version' key, which should be set to '4' for
 102   annotations that only apply to Swift 4 mode and earlier. The other entries
 103   in this dictionary are the same declaration entries as at the top level:
 104   Classes, Protocols, Tags, Typedefs, Globals, Enumerators, and Functions.
 105
 106   ::
 107
 108     SwiftVersions:
 109     - Version: 4
 110       Classes: …
 111       Protocols: …
 112
 113 Each entry under 'Classes' and 'Protocols' can contain "Methods" and
 114 "Properties" arrays, in addition to the attributes described below:
 115
 116 :Methods:
 117
 118   Identified by 'Selector' and 'MethodKind'; the MethodKind is either
 119   "Instance" or "Class".
 120
 121   ::
 122
 123     Classes:
 124     - Name: UIViewController
 125       Methods:
 126       - Selector: "presentViewController:animated:"
 127         MethodKind: Instance
 128         …
 129
 130 :Properties:
 131
 132   Identified by 'Name' and 'PropertyKind'; the PropertyKind is also either
 133   "Instance" or "Class".
 134
 135   ::
 136
 137     Classes:
 138     - Name: UIView
 139       Properties:
 140       - Name: subviews
 141         PropertyKind: Instance
 142         …
 143
 144 Each declaration supports the following annotations (if relevant to that
 145 declaration kind), all of which are optional:
 146
 147 :SwiftName:
 148
 149   Equivalent to ``NS_SWIFT_NAME``. For a method, must include the full Swift name
 150   with all arguments. Use "_" to omit an argument label.
 151
 152   ::
 153
 154     - Selector: "presentViewController:animated:"
 155       MethodKind: Instance
 156       SwiftName: "present(_:animated:)"
 157
 158     - Class: NSBundle
 159       SwiftName: Bundle
 160
 161 :SwiftImportAs:
 162
 163   For a class, possible values are ``owned`` (equivalent to
 164   ``SWIFT_SELF_CONTAINED``) or ``reference`` (equivalent to
 165   ``SWIFT_SHARED_REFERENCE``, also requires specifying ``SwiftReleaseOp`` and
 166   ``SwiftRetainOp``).
 167
 168   For a method, possible values are ``unsafe`` (equivalent
 169   to ``SWIFT_RETURNS_INDEPENDENT_VALUE``) or ``computed_property`` (equivalent to
 170   ``SWIFT_COMPUTED_PROPERTY``).
 171
 172   ::
 173
 174     Tags:
 175     - Name: OwnedStorage
 176       SwiftImportAs: owned
 177
 178 :SwiftRetainOp, SwiftReleaseOp:
 179
 180   Controls the lifetime operations of a class which uses custom reference
 181   counting. The class must be annotated as a reference type using
 182   ``SwiftImportAs: reference``. The values are either names of global functions,
 183   each taking a single parameter of a pointer type, or ``immortal`` for a type
 184   that is considered alive for the duration of the program.
 185
 186   ::
 187
 188     Tags:
 189     - Name: RefCountedStorage
 190       SwiftImportAs: reference
 191       SwiftReleaseOp: RCRelease
 192       SwiftRetainOp: RCRetain
 193     - Name: ImmortalSingleton
 194       SwiftImportAs: reference
 195       SwiftReleaseOp: immortal
 196       SwiftRetainOp: immortal
 197
 198 :SwiftCopyable:
 199
 200   Allows annotating a C++ class as non-copyable in Swift. Equivalent to
 201   ``SWIFT_NONCOPYABLE``, or to an explicit conformance ``: ~Copyable``.
 202
 203   ::
 204
 205     Tags:
 206     - Name: tzdb
 207       SwiftCopyable: false
 208
 209 :SwiftConformsTo:
 210
 211   Allows annotating a C++ class as conforming to a Swift protocol. Equivalent
 212   to ``SWIFT_CONFORMS_TO_PROTOCOL``. The value is a module-qualified name of a
 213   Swift protocol.
 214
 215   ::
 216
 217     Tags:
 218     - Name: vector
 219       SwiftConformsTo: Cxx.CxxSequence
 220
 221 :Availability, AvailabilityMsg:
 222
 223   A value of "nonswift" is equivalent to ``NS_SWIFT_UNAVAILABLE``. A value of
 224   "available" can be used in the "SwiftVersions" section to undo the effect of
 225   "nonswift".
 226
 227   ::
 228
 229     - Selector: "dealloc"
 230       MethodKind: Instance
 231       Availability: nonswift
 232       AvailabilityMsg: "prefer 'deinit'"
 233
 234 :SwiftPrivate:
 235
 236   Equivalent to NS_REFINED_FOR_SWIFT.
 237
 238   ::
 239
 240     - Name: CGColorEqualToColor
 241       SwiftPrivate: true
 242
 243 :Nullability:
 244
 245   Used for properties and globals. There are four options, identified by their
 246   initials:
 247
 248   - ``Nonnull`` or ``N`` (corresponding to ``_Nonnull``)
 249   - ``Optional`` or ``O`` (corresponding to ``_Nullable``)
 250   - ``Unspecified`` or ``U`` (corresponding to ``_Null_unspecified``)
 251   - ``Scalar`` or ``S`` (deprecated)
 252
 253   Note that 'Nullability' is overridden by 'Type', even in a "SwiftVersions"
 254   section.
 255
 256   .. note::
 257
 258     'Nullability' can also be used to describe the argument types of methods
 259     and functions, but this usage is deprecated in favor of 'Parameters' (see
 260     below).
 261
 262   ::
 263
 264     - Name: dataSource
 265       Nullability: O
 266
 267 :NullabilityOfRet:
 268
 269   Used for methods and functions. Describes the nullability of the return type.
 270
 271   Note that 'NullabilityOfRet' is overridden by 'ResultType', even in a
 272   "SwiftVersions" section.
 273
 274   .. warning::
 275
 276     Due to a compiler bug, 'NullabilityOfRet' may change nullability of the
 277     parameters as well (rdar://30544062). Avoid using it and instead use
 278     'ResultType' and specify the return type along with a nullability
 279     annotation (see documentation for 'ResultType').
 280
 281   ::
 282
 283     - Selector: superclass
 284       MethodKind: Class
 285       NullabilityOfRet: O
 286
 287 :Type:
 288
 289   Used for properties and globals. This completely overrides the type of the
 290   declaration; it should ideally only be used for Swift backwards
 291   compatibility, when existing type information has been made more precise in a
 292   header. Prefer 'Nullability' and other annotations when possible.
 293
 294   We parse the specified type as if it appeared at the location of the
 295   declaration whose type is being modified.  Macros are not available and
 296   nullability must be applied explicitly (even in an ``NS_ASSUME_NONNULL_BEGIN``
 297   section).
 298
 299   ::
 300
 301     - Name: delegate
 302       PropertyKind: Instance
 303       Type: "id"
 304
 305 :ResultType:
 306
 307   Used for methods and functions. This completely overrides the return type; it
 308   should ideally only be used for Swift backwards compatibility, when existing
 309   type information has been made more precise in a header.
 310
 311   We parse the specified type as if it appeared at the location of the
 312   declaration whose type is being modified.  Macros are not available and
 313   nullability must be applied explicitly (even in an ``NS_ASSUME_NONNULL_BEGIN``
 314   section).
 315
 316   ::
 317
 318     - Selector: "subviews"
 319       MethodKind: Instance
 320       ResultType: "NSArray * _Nonnull"
 321
 322 :SwiftImportAsAccessors:
 323
 324   Used for properties. If true, the property will be exposed in Swift as its
 325   accessor methods, rather than as a computed property using ``var``.
 326
 327   ::
 328
 329     - Name: currentContext
 330       PropertyKind: Class
 331       SwiftImportAsAccessors: true
 332
 333 :NSErrorDomain:
 334
 335   Used for ``NSError`` code enums. The value is the name of the associated
 336   domain ``NSString`` constant; an empty string (``""``) means the enum is a
 337   normal enum rather than an error code.
 338
 339   ::
 340
 341     - Name: MKErrorCode
 342       NSErrorDomain: MKErrorDomain
 343
 344 :SwiftWrapper:
 345
 346   Controls ``NS_STRING_ENUM`` and ``NS_EXTENSIBLE_STRING_ENUM``. There are three
 347   options:
 348
 349   - "struct" (extensible)
 350   - "enum"
 351   - "none"
 352
 353   Note that even an "enum" wrapper is still presented as a struct in Swift;
 354   it's just a "more enum-like" struct.
 355
 356   ::
 357
 358     - Name: AVMediaType
 359       SwiftWrapper: none
 360
 361 :EnumKind:
 362
 363   Has the same effect as ``NS_ENUM`` and ``NS_OPTIONS``. There are four options:
 364
 365   - "NSEnum" / "CFEnum"
 366   - "NSClosedEnum" / "CFClosedEnum"
 367   - "NSOptions" / "CFOptions"
 368   - "none"
 369
 370   ::
 371
 372     - Name: GKPhotoSize
 373       EnumKind: none
 374
 375 :Parameters:
 376
 377   Used for methods and functions. Parameters are identified by a 0-based
 378   'Position' and support the 'Nullability', 'NoEscape', and 'Type' keys.
 379
 380   .. note::
 381
 382     Using 'Parameters' within a parameter entry to describe the parameters of a
 383     block is not implemented. Use 'Type' on the entire parameter instead.
 384
 385   ::
 386
 387     - Selector: "isEqual:"
 388       MethodKind: Instance
 389       Parameters:
 390       - Position: 0
 391         Nullability: O
 392
 393 :NoEscape:
 394
 395   Used only for block parameters. Equivalent to ``NS_NOESCAPE``.
 396
 397   ::
 398
 399     - Name: dispatch_sync
 400       Parameters:
 401       - Position: 0
 402         NoEscape: true
 403
 404 :SwiftBridge:
 405
 406   Used for Objective-C class types bridged to Swift value types. An empty
 407   string ("") means a type is not bridged. Not supported outside of Apple
 408   frameworks (the Swift side of it requires conforming to implementation-detail
 409   protocols that are subject to change).
 410
 411   ::
 412
 413     - Name: NSIndexSet
 414       SwiftBridge: IndexSet
 415
 416 :DesignatedInit:
 417
 418   Used for init methods. Equivalent to ``NS_DESIGNATED_INITIALIZER``.
 419
 420   ::
 421
 422     - Selector: "initWithFrame:"
 423       MethodKind: Instance
 424       DesignatedInit: true