ios - 如何使用 Swift 文档注释

Question

我有几个关于 Swift 文档注释的问题:

1. 有没有办法像某些 Apple 文档那样创建相关声明部分？例如，当我 Option+Click tablewView(_:heightForRowAtIndexPath:) 方法时，它将我链接到生成的其他三个相关方法文档。

2. Swift 中有警告标签吗？我知道 Objective-C 允许我执行 @warning 并在生成的文档中获得粗体警告。但是，:warning: 在 Swift 的文档注释中没有执行任何操作，所以我很好奇是否还有其他方法。

3. 有没有办法将我的文档制作成与 Apple 文档格式相似的 HTML 文件？我知道在其他 IDE 中，例如 Eclipse，我可以为我的代码生成 HTML 文档。 XCode 有这个吗？

Answer 1

此答案最后针对 Swift 5.7 和 Xcode 14.x 进行了修订。

---

DocC是 Apple 的文档编译器，它接受评论(加上额外的资源)并生成可以在 Xcode 中查看或托管在 Web 上的丰富文档。

编写文档

键入 /// 或 /** */ 开始文档注释，然后使用 DocC 的 special dialect of Markdown写内容。此方言支持许多关键字，例如用于描述函数参数的 - Parameters: 或用于描述返回值的 - Returns:。

请注意 > Warning: 关键字是如何被识别为旁白并自动强调的。 DocC 支持多种其他旁白类型，例如 Note、Tip 和 Important。

/// Produce a greeting string for the given `subject`.
///
/// ```
/// print(hello("world")) // "Hello, world!"
/// ```
///
/// > Warning: The returned greeting is not localized. To
/// > produce a localized string, use ``localizedHello(_:)``
/// > instead.
///
/// - Parameters:
///     - subject: The subject to be welcomed.
///
/// - Returns: A greeting for the given `subject`.
func hello(_ subject: String) -> String {
    return "Hello, \(subject)!"
}

链接到符号

DocC 将自动链接(并自动完成!)包含在双反引号 `` 中的符号。您可以链接到同一类型或同一模块中其他类型的相关符号。

请注意，链接仅限于公共(public)符号，并且仅限于一个模块。到今天为止，无法输入例如``UIView`` 并让 DocC 自动将其链接到 UIKit 的文档。

生成网页

文件中心 supports将文档导出到网页中。首先，您需要通过选择 Product → Build Documentation 来编译您的文档。构建文档后，通过单击“更多”按钮导出其存档。存档将包含整个文档网页，然后您可以将其托管在您的服务器上。

上面的过程有点复杂，所以有很多工具可以帮你自动化。苹果优惠swift-docc-plugin您可以将其添加到您的 Swift 包或 Xcode 项目中，并将其配置为在每次构建时运行。您也可以在 CI 上自动执行此过程。

进一步阅读

我建议阅读以下指南以了解有关 DocC 的更多信息:

• Writing Symbol Documentation in Your Source Files
• Formatting Your Documentation Content
• Adding Structure to Your Documentation Pages
• Distributing Documentation to External Developers