Swift API Notes

Swift API Notes

在苹果的官方框架中，有以 .apinotes 为后缀的文件。苹果公司给出了如下说明：

notes provide a mechanism by which Objective-C APIs can be annotated with additional semantic information not present within the original Objective-C headers. This semantic information can then be used by the Swift compiler when importing the corresponding Objective-C module to provide a better mapping of Objective-C APIs into Swift.

API notes are organized into a set of .apinotes files. Each .apinotes file contains annotations for a single Objective-C module, written in YAML (FIXME: to be) described in the Clang repository. These YAML sources are lazily loaded by the Swift compiler when it imports the corresponding framework, also described below.

To add API notes for a system module $MODULE that does not have them yet, create a new source file $MODULE.apinotes and update CMakeLists.txt. Updated API notes will be found by the build system during the next build.

原文地址：https://github.com/apple/swift/tree/master/apinotes

大意如下：

API 注解提供了一种机制，使得 Objective-C 的 API 可以添加额外的语义信息，但不必写在框架 API 的头文件中。在导入这些框架时，相应的语义信息可以被 Swift 的编译器直接使用，从而可以将框架的 API 更好的应用在 Swift 中。

API 注解由一系列的 .apinotes 文件组成，每个 .apinotes 文件都包含单个 Objective-C 模块的注解，该注解是使用 YAML 写的，参见 Clang 库。当 Swift 导入这些模块时，Swift 的编译器只是简单的加载这些 YAML 文件。

为尚未有注解文件的系统模块添加一个注解文件时，需要创建一个以模块名称为文件名，以 .apinotes 为文件后缀的文件，写入信息后，更新 CMakeLists.txt 文件，而后，更新的 API 注解则会在下一次系统编译时显示。

YAML(YAML Ain’t a Markup Language) 文件类似标记语言，但更注重数据，可参考 OpenGLES.apinotes 的内容，如下：

---
Name: OpenGLES

SwiftVersions:
- Version: 3
  Functions:
  - Name: EAGLGetVersion
    Parameters:
    - Position: 0
      Nullability: U
    - Position: 1
      Nullability: U
  Classes:
  - Name: EAGLContext
    Properties:
    - Name: debugLabel
      PropertyKind: Instance
      Nullability: U
    - Name: sharegroup
      PropertyKind: Instance
      Nullability: U
    Methods:
    - Selector: "initWithAPI:"
      MethodKind: Instance
      NullabilityOfRet: U
    - Selector: "initWithAPI:sharegroup:"
      MethodKind: Instance
      NullabilityOfRet: U
      Nullability: [S, U]
    - Selector: "currentContext"
      MethodKind: Class
      NullabilityOfRet: U
    - Selector: "setCurrentContext:"
      MethodKind: Class
      Parameters:
      - Position: 0
        Nullability: U
    - Selector: "renderbufferStorage:fromDrawable:"
      MethodKind: Instance
      Parameters:
      - Position: 1
        Nullability: U
  - Name: EAGLSharegroup
    Properties:
    - Name: debugLabel
      PropertyKind: Instance
      Nullability: U
  Protocols:
  - Name: EAGLDrawable
    Properties:
    - Name: drawableProperties
      PropertyKind: Instance
      Type: "NSDictionary*"