ios 如何使用 Swift 文档注释
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/27715933/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
How to use Swift documentation comments
提问by ad121
I have a few questions about Swift documentation comments:
我有几个关于 Swift 文档注释的问题：
Is there a way to make a Related declarations section like some of the Apple documentation has? For example, when I Option+Clickthe
tablewView(_:heightForRowAtIndexPath:)method, it links me to three other related methods within the generated documentation.Is there any warning tag in Swift? I know Objective-C allowed me to do
@warningand get a bolded warning in the generated documentation. However,:warning:does nothing in Swift's documentation comments, so I was curious if there was another way.Is there a way to make my documentation into an HTML file that is a similar format as the Apple Documentation? I know in other IDEs, such as Eclipse, I can generate HTML documentation for my code. Does XCode have this?
有没有办法像某些 Apple 文档那样制作相关声明部分？例如，当我Option+Click的
tablewView(_:heightForRowAtIndexPath:)方法，它链接我在生成的文档中的其他三个相关的方法。Swift 中是否有任何警告标签？我知道 Objective-C 允许我这样做
@warning并在生成的文档中得到一个粗体警告。但是，:warning:在 Swift 的文档注释中什么也没做，所以我很好奇是否有另一种方式。有没有办法将我的文档制作成与 Apple 文档格式类似的 HTML 文件？我知道在其他 IDE（例如 Eclipse）中，我可以为我的代码生成 HTML 文档。XCode 有这个吗？
回答by akashivskyy
This answer was last revised for Swift 5.2 and Xcode 11.4.
此答案最后一次针对 Swift 5.2 和 Xcode 11.4 进行了修订。
You can use markupto write standard code documentation (using ///or /** */) and rich playground documentation (using //:or /*: */).
您可以使用标记来编写标准代码文档（使用///或/** */）和丰富的操场文档（使用//:或/*: */）。
/// This function returns a welcoming string for a given `subject`.
///
/// ```
/// print(hello("World")) // Hello, World!
/// ```
///
/// - Warning: The returned string is not localized.
/// - Parameter subject: The subject to be welcomed.
/// - Returns: A hello string to the `subject`.
func hello(_ subject: String) -> String {
return "Hello, \(subject)!"
}
As for documenting related symbols, there is a SeeAlsomarkup tagbut requires you to write an explicit URL to your related symbol's documentation page.
至于记录相关符号，有一个SeeAlso标记标签，但要求您为相关符号的文档页面写一个明确的 URL。
If you want to generate HTML documentation index for your project, I recommend checking out jazzyand swift-doc. They're both amazing open-source projects, and are even used by Apple itself.
如果您想为您的项目生成 HTML 文档索引，我建议您查看jazzy和swift-doc。它们都是了不起的开源项目，甚至被 Apple 自己使用。
回答by stevo.mit
Xcode 7.0 beta 4
Xcode 7.0 测试版 4
The notation has been changed (:param:does not work anymore ...)
符号已更改（: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!"
}
And it looks like this:
它看起来像这样：
You can use either ///or /** */
您可以使用///或/** */
回答by abhimuralidharan
For those who want to add this as code snippet. Swift 5, XCode 11.3+
对于那些想要将其添加为代码片段的人。Swift 5，XCode 11.3+
This is an add on to : Yogendra Singh's Answer in this thread
这是一个补充：Yogendra Singh 在这个线程中的回答
/**
<#Summay text for documentation#>
- parameter <#parameterName#>: <#Description#>.
- returns: <#Return values#>
- warning: <#Warning if any#>
# Notes: #
1. <#Notes if any#>
# Example #
```
// <#Example code if any#>
```
*/
Copy and paste the above code in Xcode. Select the code and then Right click.
将上面的代码复制并粘贴到 Xcode 中。选择代码，然后右键单击。
Save the code snippet and give the completion name as documentation.
保存代码片段并提供完成名称作为文档。
Now if we start typing documentation, the snippet will be shown in the code completion.
现在，如果我们开始输入文档，代码段将显示在代码完成中。
回答by Yogendra Singh
Use the following notation for documentation comments.
对文档注释使用以下符号。
/**
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
}
回答by AliSoftware
(3) To generate your documentation in HTML (or even generate docsets), I strongly recommend jazzywhich was built for that purpose.
(3) 要以 HTML 格式生成文档（甚至生成文档集），我强烈推荐为此目的而构建的jazzy。
Even if it's still WIP, it works really well and generate documentation with similar presentation to the Apple documentation
即使它仍然是 WIP，它也能很好地工作并生成与 Apple 文档类似的文档
