语法(七) – 文档标记

Markdown

Markdown 注释以 /** 开始，以 */ 结束。

/**
Call this function to grok some globs.
*/
func myGreatFunction() {
    // do stuff
}

常见的 Markdown 格式，如下

Place text in `backticks` to mark code; on your keyboard these usually share a key with tilde, ~.
* You can write bullets by starting with an asterisk then a space.
    * Indent your asterisks to create sublists
1. You can write numbered listed by starting with 1.
1. Subsequent items can also be numbered 1. and Xcode will renumber them automatically.

If you want to write a link, [place your text in brackets](and your link in parentheses)
# Headings start with a # symbol
## Subheadings start with ##
### Sub-subheadings start with ### and are the most common heading style you'll come across
Write a *single asterisk* around words to make them italic
Write **two asterisks** around words to make them bold

文件关键词

Swift 允许添加特殊关键字，这些关键字会显示在快速帮助窗格中，Xcode 文档注释快捷键 Command + Option + / 即 (⌘ + ⌥ + /)。

/// 计算两点之间的距离
/// - Parameters:
///   - start: 起点
///   - end: 终点
///   - technique: 采用的计算方式
/// - Returns: 两点之间的距离
/// - Complexity: O(1)
/// - Authors: jiulinxiri
func calculateDistance(start: Point, end: Point, technique: DistanceTechnique) -> Double {
	// ...
}

Returns

通过 Returns 关键字，您可以指定函数成功运行时调用者可以期待返回的值。

- Returns: A string containing a date formatted as RFC-822

Parameter

通过该关键字，您可以指定参数的名称并描述其包含的内容。

- Parameter album: The name of a Taylor Swift album
- Parameter track: The track number to load

Throws

通过该关键字，您可以指定一个以逗号分隔的错误类型列表，该列表列出了函数可能抛出的错误类型。

- Throws: LoadError.networkFailed, LoadError.writeFailed

Precondition

它应该用来描述函数被调用前程序的正确状态。如果您使用的是纯函数，这个前提条件应该只依赖于传入函数的参数。

- Precondition: inputArray.count > 0

Complexity

这在快速帮助中没有特别的格式，但对于其他使用你的代码的人来说是有用的信息。

- Complexity: O(1)

Authors

这个关键字用于将函数作者的姓名写入快速帮助窗格中，当您需要找出应该向谁投诉和/或表扬谁的工作时，这个关键字会很有帮助。

- Authors: Paul Hudson