Swift文档评论

Question

我有一些关于Swift文档评论的问题。

1. 无论如何都要像一些Apple文档那样制作一个相关的声明部分。例如，当我选择+单击tablewView（_：heightForRowAtIndexPath :)方法时，它会将我链接到生成的文档中的其他3个相关方法。

2. swift中是否有警告标签？我知道在objective-c中它允许你做@warning并在生成的文档中得到一个粗体警告。但是，：警告：在快速的文档评论中什么都不做，所以我很好奇是否有另一种方式。

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

Answer 1

您可以使用markup编写游乐场和代码文档注释。

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

实施例

/// 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。否。在there is a SeeAlso markup tag时，它还不够聪明，无法链接到您或第三方库中的相关符号。

广告。 2。是的，there is a Warning markup tag。请参阅上面的示例。

广告。 3。 Altough Xcode can generate XML representation of the documentation comments，它无法生成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's Answer in this thread

的添加

increment()

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

保存代码段，并将完成名称作为文档。

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

Answer 4

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

即使它仍然是WIP，它也能很好地生成与Apple文档具有类似表现形式的文档

Answer 5

对于Swift代码，Apple删除了HeaderDoc并切换为Markdown style语法。他们选择了Markdown的CommonMark变体，其中包含一些Swift特定的关键字扩展名。

符号文档

共有四个部分，其中始终仅包含描述：

• 说明
• 参数
• 投掷
• 退货

在描述之后，其他部分的顺序无关紧要。您只能有一个“掷球”和一个“返回”部分。

/**
 What does this function do?

 Some discussion

 - Parameters:
    - firstParam: Describe the first param
    - secondParam: Describe the second param
 - Returns: true or false
 - Throws: SomeError you might want to catch
 */
func someFunction(firstParam: String, secondParam: String) throws -> Bool {
    return true;
}

  

如果文档注释以段落以外的任何内容开头，则其所有内容都将放入讨论中。

关键字快速向导

如果想花哨的话，可以在说明中的任意位置添加一长串关键字。

- Attention: - Author: - Authors: - Bug: - Complexity: - Copyright:
- Date: - experiment: - important: - invariant: - Note: - Precondition:
- Postcondition: - Remark: - Requires: { {1}} - seealso: - Since: - Todo:
- Version:

要自动生成文档，请按⌘命令 + ⌥选项 + / 或- Warning:

了解更多here

Answer 6

使用以下符号表示文档注释。

/**
 This method sum two double numbers and returns.

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