Swift 文档：instance/type property/method 表示法

Question

要记录 Ruby，我会写 Time::now 或 Time#day。我如何记录 Swift?

也就是说，在记录 Swift 时，类型及其 1) 类型属性或方法或 2) 实例属性或方法的表示法是什么？

例如，在 Ruby 文档中，符号 ::（两个冒号）表示 class 属性或方法，而符号 # （数字符号、井号、井号标签或井号）表示实例属性或方法。因此，Time::now 意味着 now 是 class 属性或 Time 的方法，而 Time#day 意味着 day 是一个实例属性或 Time.

的方法

Swift文档有这样的符号语法吗？

我知道 Swift 文档的函数表示法——例如，Swift append(_ newElement: Element) method for Array 被记录为 append(_:)——因为我在 Apple 的文档。但是，如何为 Swift 编写 Array#append(_:)？

Answer 1

如果您询问的是文档，我建议您查看 Jazzy，这是一种用于根据内联代码注释构建文档的工具。这是从您的代码注释构建独立文档的好方法，并且符合 Apple 的惯例。

使用的基本约定如下。假设您有一些 class 定义如下：

/// Some incredibly useful class

public class MyClass {

    /// Performs some foo-like operation
    ///
    /// - Parameter bar: The bar parameter.

    public class func foo(_ bar: String) {
        // do something
    }

    /// Some bazzy operation
    ///
    /// - Parameter qux: The bar parameter.

    public func baz(_ quz: String) {
        // do something
    }
}

Jazzy 将生成如下所示的文档：

请注意，它只是向您显示参数标签。如果你点击一个，它会告诉你它是否是一个类型方法以及参数名称是什么：

在最初的问题中，您并不清楚您在谈论文档，因此我讨论了人们在代码中遇到的约定。该答案如下。

在 Swift 中，实例和属性类型都是 .。

这只是 . 之前的问题。如果是类型，就是类型property/method。考虑：

let b = Foo.bar

这是 Foo 类型的引用类型属性 bar。但是，如果 . 之前的是一个类型的实例，那么您正在处理一个实例 property/method。考虑：

let b = Baz()
let q = baz.qux

在这种情况下，qux 引用 Baz 的实例属性，因为 b 是 Baz 类型的实例。

冒着混淆问题的风险，对上述模式的警告是在 Swift 中使用 "selectors"（较旧的 Objective-C 模式）。在这种情况下，选择 target 表示 selector 引用的内容。如果您为 target 提供实例，则 selector 引用实例方法。如果您为 target 提供类型，那么 selector 将引用类型方法。因此，在此示例中，selector 引用实例方法：

Timer.scheduledTimer(timeInterval: 1, target: self, selector: #selector(ViewController.foo), userInfo: nil, repeats: false)

而以下将调用类型方法：

Timer.scheduledTimer(timeInterval: 1, target: ViewController.self, selector: #selector(ViewController.foo), userInfo: nil, repeats: false)

请注意，在这两个示例中，如果我们在同一个 class 中进行交互，我们通常会完全省略 class 名称。如果它在另一个 class 中，您只需要显式引用该类型。但是我包含这个 target/selector 模式仅仅是因为它确实显示了另一个稍微不同的 Class.method 语法的使用。

但这个例外是独一无二的。一般模式是 xxx.yyy，其中如果 xxx 是某种类型的实例，则 yyy 是实例 property/method，而如果 xxx 是某些类型的名称类型，那么 yyy 是一个类型 property/method.

append(_ newElement:) 与 append(_:) 的引用完全不同。这只是第一个参数 newElement 没有外部标签的情况，因此调用时没有标签，例如array.append(object)。所以 append(_:) 只是一个符号，向您展示它是如何调用的（我们不关心内部参数名称是什么），但 append(_ newElement:) 是它的实现方式（我们确实想知道如何在方法中引用此参数）。

Answer 2

不幸的是 Swift 没有官方或 widely-accepted 符号来区分类型 properties/methods 和实例 properties/methods 类型名称前缀形式。

（所以，通常的 Swift 程序员（甚至专家）无法理解你的问题。）

类型名称前缀形式实际上在 Swift book 中使用，但并不经常使用。

据我检查：

在某些部分，类型属性以 UInt32.max 的形式引用，但如您所见，这只是使用有效的实际符号 Swift表达式.
在其他一些地方，type method 被称为像 LevelTracker.unlock(_:) 的形式，但这在 Swift 中也是一个有效的表达式，我不确定 Apple正在使用它作为类型方法的文档符号。我无法快速浏览 Swift 书中的示例，但初始化器通常以 String.init(data:encoding:) 之类的形式引用，这也是 Swift.[=25 中的有效表达式=]
对于其他情况，实例方法或属性被称为instanceVar.methodName(_:)或instanceVar.propertyName，当然instanceVar出现在附近的代码片段中而不是类型名称，这实际上不是您要查找的内容。

如您所知，在 Apple 的官方参考资料中，方法或属性的标题为 Instance method、Type method、实例属性 或 类型属性。或前缀为 class/static var/let、class/static func、var/let 或 func.

我无法通过非常简短的调查找到示例，但某些文章（包括 Apple 的文章）可能也以 TypeName.methodName(_:)（或实例属性形式引用实例方法。 ) 似乎 Swift 社区认为区分类型成员和实例成员并不重要。

我不能花太多时间，但似乎很明显

Swift 没有官方或 widely-accepted 符号来区分类型 properties/methods 和带有类型名称前缀形式的实例 properties/methods。

也许你需要写一些类似实例方法 Array.append(_:)来表示Array#append(_:).

（请注意，Array.append(_:) 也是 Swift 中的有效表达式。）

Swift 文档：instance/type property/method 表示法

Swift documentation: instance/type property/method notation

documentation

class

instance

notation

swift