[Upstream] Add APINotes support for Swift

Author: MForster

clang/docs/APINotes.rst

@@ -0,0 +1,361 @@
+================================================
+API Notes: Annotations Without Modifying Headers
+================================================
+
+**The Problem:** You have headers you want to use, but you also want to add
+extra information to some of the APIs. 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 APIs 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`__ from the compiler test suite of API
+notes for a hypothetical "SomeKit" framework.
+
+__ https://github.com/apple/swift-clang/blob/upstream-with-swift/test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKit.apinotes
+
+
+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
+``-fapinotes-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. ``-fapinotes-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:
+
+  - "N"onnull (``_Nonnull``)
+  - "O"ptional (``_Nullable``)
+  - "U"nspecified (``_Null_unspecified``)
+  - "S"calar (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.
+
+  Note that the type is *not* parsed in the context where it will be used,
+  which means that 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.
+
+  Note that the type is *not* parsed in the context where it will be used,
+  which means that 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

clang/docs/index.rst

@@ -44,6 +44,7 @@ Using Clang as a Compiler
    OpenCLSupport
    OpenMPSupport
    ThinLTO
+   APINotes
    CommandGuide/index
    FAQ