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
}

继续阅读“Swift 文档编写规范”