我有几个关于Swift文档注释的问题：
是否有办法创建一个“相关声明”(Related declarations)部分，就像一些苹果官方文档中的那样？例如，当我使用 Option+Click 点击 tablewView(_:heightForRowAtIndexPath:) 方法时，它会在生成的文档中链接到另外三个相关方法。
Swift 中有警告标签吗？我知道 Objective-C 允许我使用 @warning 来获得粗体突出的警告信息。然而，在 Swift 的文档注释中使用 :warning: 并不起作用，所以我想知道是否还有其他方式。
是否有办法将我的文档注释制作成一个类似苹果官方文档格式的 HTML 文件？我知道在其他 IDE（如 Eclipse）中，我可以为我的代码生成 HTML 文档，那么 XCode 是否也有这个功能呢？
本回答最后修订于 Swift 5.7 和 Xcode 14.x。
DocC 是苹果的文档编译器，它接收注释（以及其他资源），并生成可以在Xcode中查看或托管在Web上的丰富文档。
输入///或/** */开始文档注释, 然后使用 DocC 的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会自动链接（并自动完成！）用双反引号``包围的符号。您可以在同一类型或同一模块中链接到相关符号。
请注意，链接仅限于公共符号，并且仅限于一个模块。截至今天，没有办法输入“UIView”等内容，让DocC自动将其链接到UIKit文档。
DocC支持将您的文档导出为网页。首先，您需要通过选择产品→构建文档来编译您的文档。构建文档后，单击“More”按钮导出其存档。存档将包含整个文档网页，您可以将其托管在您的服务器上。
以上过程有点复杂，因此有许多工具可帮助您自动化。Apple提供了swift-docc-plugin，您可以将其添加到Swift包或Xcode项目中，并配置它在每次构建时运行。您也可以在CI上自动化此过程。
我建议阅读以下指南以了解有关DocC的更多信息：
Xcode 7.0 beta 4
标注已更改 （:param: 不再起作用...）
/// Creates the string representation of the poo with requested size.
///
/// - warning: Be carefull! Poos can hurt.
/// - parameter size: requested size of the poo
/// - returns: string representation of the poo
func makePoo(size: String) -> String
{
return "Ouch. This is \(size) poo!"
}
它看起来像这样：
您可以使用///或/** */。
/**
<#Summay text for documentation#>
- parameter <#parameterName#>: <#Description#>.
- returns: <#Return values#>
- warning: <#Warning if any#>
# Notes: #
1. <#Notes if any#>
# Example #
```
// <#Example code if any#>
```
*/
使用以下符号来编写文档注释。
/**
This method sum two double numbers and returns.
Here is the discussion. This methods adds two double and return the optional Double.
- parameter number1: First Double Number.
- parameter number2: Second Double Number.
- returns: The sum of two double numbers.
# Notes: #
1. Parameters must be **double** type
2. Handle return type because it is optional.
# Example #
```
if let sum = self.add(number1: 23, number2: 34) {
print(sum)
}
```
*/
func add(number1: Double, number2: Double) -> Double? {
return number1 + number2
}
Xcode中的键盘快捷方式
option + cmd + /
(3) 为了生成HTML文档（甚至生成docsets），我强烈推荐使用专门为此目的而建的jazzy。
尽管它仍在进行中，但它的功能非常强大，并且可以生成类似于Apple文档的漂亮的文档。
CMD+OPTION+/快捷键，Xcode会为所有所需文档（包括返回值、参数等）添加模板。它可以是扩展、类、方法等。这样你就可以保证使用官方的文档格式/风格。 - rgkobashi