Swift文档评论

Question

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

1. 反正有没有像一些Apple文档那样制作一个相关的声明部分。例如，当我选择+单击tablewView（_：heightForRowAtIndexPath :)方法时，它会将我链接到生成的文档中的其他3个相关方法。
2. swift中有警告标签吗？我知道在objective-c中它允许你做@warning并在生成的文档中得到一个粗体警告。但是，：警告：在快速文档评论中没有任何作用，所以我很好奇是否还有其他方法。
3. 有没有办法让您的文档成为与Apple文档类似格式的HTML文件。我知道在其他IDE中用于其他语言，例如Eclipse，您只需为代码生成html文档。 XCode有这个吗？

Answer 1

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

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

Example

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

Answers to your questions

广告。 1.不。在there is a SeeAlso markup tag时，它还不够聪明，无法链接到您或第三方库中的相关符号。

广告。是的，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

（3）要用HTML生成文档（甚至生成docsets），我强烈推荐为此目的而构建的jazzy。

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

Answer 4

对于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: - seealso: - Since: - Todo: - Version: - Warning:

要自动生成doc，请按⌘命令c⌥选项/或qazxsw poi

阅读更多Editor -> Structure -> Add Documentation

Answer 5

使用以下表示法进行文档注释。

here

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