Swift 注释 "tag"

Question

自从 Objective-C 以来，我就是 #pragma MARK: 的粉丝，但最近我在 Apple 的源代码中看到了 /// -Tag:。同样值得注意的是，它以白色突出显示，而 MARK 则不是。 Tag 另一边不向 Xcode 'outline' 视图添加任何文本。

谁能解释一下 Tag 的目的是什么？

Answer 1

我找不到任何特定于 Tag 文档关键字的内容。它似乎是一个自定义文档关键字，尽管它没有按预期出现在快速帮助中...

我猜它可能只是一种允许搜索相关代码的方式...也许它会在未来作为一项新功能出现 - 用于将 "tags" 应用于特定符号，就像您在 Finder 中一样。这似乎是合理的，因为问题中引用的函数与自定义集群相关（请参阅 Decluttering a Map with MapKit Annotation Clustering），并且文档行显示 /// - Tag: CustomCluster.

编写函数时，可以使用 "markdown" 的版本在 Swift 中记录该函数的详细信息。有关示例，请参阅 Markup Formatting Reference and CommonMark。

此文档出现在 Quick Help 弹出框中，如问题所示，以及 Quick Help Inspector - 显示在当您的光标位于一个符号（例如函数名称）中时，您会在右侧面板中单击检查器面板顶部圆圈中的问号。

本文档存在许多预定义关键字，例如 - Parameters:、- Returns: 和 - Throws:。并且，您还可以使用自己的自定义关键字。通常自定义关键字也会出现在 快速帮助 中，但是这个 - Tag: 关键字似乎没有任何作用（至少在 Xcode 9.4.1 中） .

下面是如何使用 Swift 文档标记的示例：

/// Errors associated with String processing.
enum StringError: Error {
    case cantCapitalizeAnEmptyString
}

/// Capitalizes a String item.
/// - Tag: I don't know what this is - it doesn't show in Quick Help.
/// - Parameter string: A String item to be capitalized.
/// - Throws `StringError.cantCapitalizeEmptyString` when provided String item is empty.
/// - Returns: The provided String item converted to all capital letters.
/// - Blah: A custom keyword I made up.
func capitalize(string: String) throws -> String {
    if string.isEmpty {
        throw StringError.cantCapitalizeAnEmptyString
    }
    return string.capitalized
}

然后，在快速帮助检查器中，您会看到：

或者，当然，按住选项并单击函数名称将显示 快速帮助 弹出窗口：

如问题中所述，- Tag: 关键字在 Quick Help Inspector 或 Quick Help 弹出窗口中均未显示任何内容.

Answer 2

- Tag: 注释可用于引用您自己代码的某些地方，并且是 swift 文档降价语法的一部分。这是一个简化的例子：

/// - Tag: myFunction
func myFunction() {
  print("My function is called")
}

/// Uses [myFunction](x-source-tag://myFunction) internally
func anotherFunction() {
  myFunction()
}

当您打开 anotherFunction 的 快速帮助 弹出窗口时，您单击 myFunction link 它将带您到 - Tag: myFunction 用于代码

Swift 注释 "tag"

Swift annotation "tag"

ios

swift

comments