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 26<https://github.com/llvm/llvm-project/blob/main/clang/test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKit.apinotes>`_ 27from the compiler test suite of API 28notes for a hypothetical "SomeKit" framework. 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