Swift 文档编写规范

本篇为译文,原文可见:链接

如果超过 6 个月没看过自己写的代码的话,你可能会认为这些代码是其他人写的。

-Eagleson’s Law

当我们使用 Appleclass 时,如果不知道如何使用它们的话,我们有很多方式可以去查找资料。比如你可以通过 Apple Developer Documentation 在线文档或者通过 Xcode 来查找。

Quick help popover

你可以通过 ⌥ – Option + click 方式查看任何 class

Symbol inspector Quick Help

Quick help 也显示在 Quick Help 检查面板(inspector panel)上。

Code completion hint

当你开始打字时,Xcode 将会有相应的提示信息(包含 class 中的 function/property/enum

接下来将介绍如何给自己的代码加上这些提示。

Syntax

给代码写文档就像写注释一样,但是有一点点语法上的差别。你需要 /// 来标注单行的文档。

/// This is your User documentation.
struct User {
    let firstName: String
    let lastName: String
}

对于多行文档,你需要 /** ... */ 符号。

/**
    This is your User documentation.
    A very long one.
*/
struct User {
    let firstName: String
    let lastName: String
}

Summary and Discussion

上述文档注释将会生成一个包含 summary 的文档。

如果要增加 discussion 区域,你只需要编写另一段即可。非第一段的内容都将属于 discussion 区域。

注:Swift 的文档注释支持 Markdown 语法。Markdown 中段落是根据空行数(需大于等于 1 个空行)分隔的。

因此,上述例子包含了两句话(属于同一个段落),它们将属于 summary 区域。

/**
    This is your User documentation.
    A very long one.
*/

如果想要第二句话出现在 discussion 区域,在两个句子之间加入一个新空行就可以了。

/**
    This is your User documentation (This is summary).

    A very long one (This will be shown in the discussion section).
*/

你也可以在文档中使用标准的 markdown 语法。

/**
 This is your User documentation.
 A very long one.

 # Text
 It's very easy to make some words **bold** and other words *italic* with Markdown. You can even [link to Google!](http://google.com)

 # Lists
 Sometimes you want numbered lists:

 1. One
 2. Two
 3. Three

 Sometimes you want bullet points:

 * Start a line with a star
 * Profit!

 Alternatively,

 - Dashes work just as well
 - And if you have sub points, put two spaces before the dash or star:
   - Like this
   - And this
*/
struct User {
    let firstName: String
    let lastName: String
}

效果如下:

对于注释 classproperty 或者简单的 functionSummarydiscussion 足够了。对于复杂的 function,我们可以添加更多的区域来展现。

Parameters

对于带参数的 function,你可以在 Quick Help 添加 parameter 区域。有两种方式可以给参数添加注释,一个是 Parameters Section,另一个是 separate Parameter Fields

Separate Parameter Fields

- Parameter x: ...
- Parameter y: ...

Parameters Section

这种声明方式满足多参数的 function。对于多参数的 funcion 来说,如果使用 Separate Parameter Fields 方式的话,可能会显得比较冗余。

- Parameters:
  - x: ...
  - y: ...
  - z: ...

Returns

对于一个有返回值的 function,你可以添加 return 区域,语法跟添加参数类似。

- Returns: ...

注:你可以指定多个返回值,但是只有最后一个会显示在 Xcode 中的 QuickHelp

Throws

Throws 语法如下:

- Throws: ...

被标记为 ThrowsFunctions 需要包含 error 描述和对应的场景。

/// A way that this user greets others.
///
/// Use this method to get the greeting for the user. The person you specify don't affect the way user greet, just the first name, and last name will be used.
/// - Warning: The greeting is always in the caller localization.
/// - Throws:
///     - <code>MyError.invalidPerson</code>
///     if <code>person</code> is not known by the caller.
///     - <code>MyError.hardToPronounce</code>
///     if <code>person</code> name is longer than 20 characters.
/// - Parameter person: <code>User</code> you want to greet
/// - Returns: A greeting of the current <code>User</code>.
func greeting(person: User) throws -> String {
  return "Hello \(person.firstName) \(person.lastName)"
}

注:注释中只能处理一个 Thorws,不支持多个 Throws

Auto-generate Quick Help documentation

Xcode 提供了一种简易方式来生成文档。在任何想要加文档注释的地方,按下 ⌥ – Option + ⌘ - command + /,或通过 Xcode 菜单 Editor > Structure > Add documentation,Xcode 将会为你生成文档模版。

/// <#Description#>
/// - Parameter person: <#person description#>

注:这个功能在不同的 Xcode 版本上可能会不一样。

Extra Fields

文档中可以添加 Callout ,语法如下:

- Callout: description

下面这些是你能使用的 Callout

- Attention: ...
- Author: ...
- Authors: ...
- Bug: ...
- Complexity: ...
- Copyright: ...
- Date: ...
- Experiment: ...
- Important: ...
- Invariant: ...
- Note: ...
- Postcondition: ...
- Precondition: ...
- Remark: ...
- Remarks: ...
- Requires: ...
- See: ...
- Since: ...
- Todo: ...
- Version: ...
- Warning: ...

Callout 将呈现在 Quick Help 中,它处于 discussion 区域下面。

示例如下:

/// A way that this user greets others.
///
/// Use this method to get the greeting for the user. The person you specify don't affect the way user greet, just the first name, and last name will be used.
/// - Warning: The greeting is always in the caller localization.
/// - Parameter person: <code>User</code> you want to greet
/// - Returns: A greeting of the current <code>User</code>.
func greeting(person: User) -> String {
  return "Hello \(person.firstName) \(person.lastName)"
}

总结

编写一个好文档并不容易,往往是比较耗时的。但是好文档的价值将会在未来体现出来。

发表评论

电子邮件地址不会被公开。 必填项已用*标注