Swift文档评论

Question

我有一些关于Swift文档注释的问题.

1. 反正有没有像一些Apple文档那样制作一个相关的声明部分.例如,当我选择+单击tablewView(_:heightForRowAtIndexPath :)方法时,它会将我链接到生成的文档中的其他3个相关方法.

2. swift中有警告标签吗？我知道在objective-c中它允许你做@warning并在生成的文档中得到一个粗体警告.但是,:警告:在快速文档评论中没有任何作用,所以我很好奇是否还有其他方法.

3. 有没有办法让您的文档成为与Apple文档类似格式的HTML文件.我知道在其他IDE中用于其他语言,例如Eclipse,您只需为代码生成html文档.XCode有这个吗？

Answer 1

您可以使用标记来编写游乐场和代码文档注释.

• 对于丰富的游乐场文档使用//:或/*: */
• 对于代码文档使用///或/** */

例

/// This function returns a *hello* string for a given `subject`.
///
/// - Warning: The returned string is not localized.
///
/// Usage:
///
///     println(hello("Markdown")) // Hello, Markdown!
///
/// - Parameter subject: The subject to be welcomed.
///
/// - Returns: A hello string to the `subject`.
func hello(subject: String) -> String {
    return "Hello, \(subject)!"
}

你的问题的答案

广告.1.否.虽然有SeeAlso标记标记,但它还不够聪明,无法链接到您或第三方库中的相关符号.

广告.2.是的,有一个Warning标记标签.看我上面的例子.

广告.3. Altough Xcode 可以生成文档注释的XML表示,它不能生成HTML文件.我推荐使用jazzy.

Answer 2

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!"
}

它看起来像这样:

你可以使用///或/** */

Answer 3

对于那些想要将其添加为代码片段的人。Swift 5，XCode 11.3+

这是一个补充：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#>
```

*/

将上面的代码复制并粘贴到 Xcode 中。选择代码，然后右键单击。

保存代码片段并提供完成名称作为文档。

现在，如果我们开始输入文档，代码段将显示在代码完成中。

Answer 4

使用以下符号作为文档注释。

/**
 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
}

Answer 5

Xcode 中的键盘快捷键

option + cmd + /

Answer 6

(3) 要以 HTML 格式生成文档（甚至生成文档集），我强烈推荐为此目的而构建的jazzy。

即使它仍然是 WIP，它也能很好地工作并生成与 Apple 文档类似的文档