Swift注释中的“Tag”

Question

自从学习Objective-C以来，我就一直喜欢使用#pragma MARK:，但最近我在苹果的源代码中看到了/// -Tag:。值得注意的是，它被用白色高亮显示，而MARK没有。另一方面，Tag并不会向Xcode的“大纲”视图中添加任何文本。

有人能解释一下Tag的目的吗？

- Carsten

---

XCode的哪个版本？ - Kerberos

版本9.4.1（9F2000） - Carsten

只是一个术语注释：#pragma MARK:（或Swift中的// MARK:）是一种组织代码的方式。您可以在Xcode顶部的跳转栏中搜索标记（单击类或结构名称以查看对象中的符号）。/// - Tag:是快速帮助显示的项目，它允许您记录或查看有关特定符号（函数或变量）的信息，就像本例中一样。虽然它们都是文档形式，但它们具有非常不同的目的和功能。 - leanne

这个回答解决了你的问题吗？如何在Xcode文档中添加到另一个方法的链接/引用？ - The Dreams Wind

当然可以，但那是新的东西。回到2018年，当时我们还没有这样的花哨功能。 - Carsten

Answer 1

- Tag:注释用于定位您自己代码中的特定位置。您可以将其包含在Swift符号文档的一部分中。例如，您可以在某个Swift文件中的函数旁边添加一个Tag标记。

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

在另一个文件中，您可以引用此代码中的确切位置作为另一个Swift实体文档的一部分：

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

在Xcode中使用快速帮助弹出框，针对anotherFunction，您将获得一个交互式参考（位于myFunction文本下方），该参考将带您到包含/// - Tag: myFunction的文件（和行）：

- The Dreams Wind

Answer 2

我无法找到与Tag文档关键字相关的任何具体信息。虽然它没有像预期的那样出现在快速帮助中，但它似乎是一个自定义文档关键字...

我猜想它可能只是一种允许搜索相关代码的方式...也许它将作为未来的新功能出现 - 用于将“标签”应用于特定符号，就像在Finder中一样。考虑到问题中引用的函数与自定义聚类有关（请参见使用MapKit注释聚类整理地图），文档行说/// - Tag: CustomCluster，这似乎是合理的。

---

当你编写一个函数时，你可以使用 Swift 中的一种“markdown”版本来记录该函数的详细信息。请参见 Markup Formatting Reference 和 CommonMark 以获取示例。

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

许多预定义的关键字用于此文档，例如 - Parameters:、- Returns: 和 - Throws:。而且，您还可以使用自己的自定义关键字。通常，自定义关键字也会出现在 Quick Help 中，但是这个 - 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
}

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

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

正如问题中所指出的，- Tag: 关键字在 快速帮助检查器 或 快速帮助弹出窗口 中都不会显示任何内容。

- leanne