如何非常惬意的在 Xcode 中为代码添加注释文档

大熊猫侯佩
0 阅读4分钟

在这里插入图片描述

概述

俗话说得好：注释当为马前卒，文档须作急先锋！ 作为似秃似不秃小码农，我们必须将编写代码注释和文档时刻牢记于心。

在这里插入图片描述

Xcode 是苹果开发中的重量级武器，为了给秃头码农们飞一般的感受，它自然对代码文档的编写提供了非同一般的支持。

在本篇博文中，您将学到如下内容：

  1. 为方法自动生成文档模版
  2. 为枚举类型创建注释文档
  3. 在 Xcode 轻松编译 DocC 文档
  4. 未来的憧憬

相信学完本课后，大家对 Xcode 如何为代码“镀金”必将了然于胸。那还等什么呢？让我们马上开始代码“镀金”之旅吧！

Let's go！！！;)

1. 为方法自动生成文档模版

正如之前《“三斜杠剑法”：DocC 绝学让代码生成的真经“叱咤武林”》那篇博文所说的那样，我们可以默念 DocC 心决，并且狂舞“三斜杠剑法”潇洒的留下一行行夺人眼球的文档真经。

不过，要记下那些“冗长”的 DocC 口诀可能会让有些小伙伴们有些干着急。

所幸的是，Xcode 早就为我们考虑到了这一切。大家只需选中指定方法，然后灵巧的按下 Option + Command + / 神秘快捷键即可自动生成文档注释模版：

extension Array {
    func destined(count: Int, allowCheat: Bool = false, whosYourDaddy: String = "war3") throws -> [Element] {
        // 实现你们不用关心...😏
        return []
    }
}

实际效果如下图所示：

在这里插入图片描述

在文档模版闪现之后，我们可以继续闪电般的将其中的信息补充完整：

extension Array {
    /// 为你找到数组中命中注定的那一个元素！快念出口诀：太上老君急急如律令！
    /// - Parameters:
    ///   - count: 需要元素的个数
    ///   - allowCheat: 是否允许作弊
    ///   - whosYourDaddy: 一种古老的作弊码
    /// - Returns: 命中注定的所有元素！
    func destined(count: Int, allowCheat: Bool = false, whosYourDaddy: String = "war3") throws -> [Element] {
        // 实现你们不用关心...😏
        return []
    }
}

正如“武林码农秘谈”第 15 章所说的那样，按下 Option 键并用鼠标右键选中 destined 方法，然后立见分晓：

在这里插入图片描述

2. 为枚举类型创建注释文档

除了为方法创建注释文档以外，我们还可以调皮的为代码中各种类型创建注释。这里就拿 Swift 中的枚举（enum）来举一个“小栗子”吧。

在下面的代码中，我们施展“三斜杠”剑法直接在枚举顶部寥寥比划了几招，颇有点“铁指银钩”的风范：

/// 随机错误，如何为其中每个 case 镀金？
enum RandomError: Error {
    case random
    case bad
    case good
}

不过，这样产生的注释无法细粒度描述 RandomError 中每一个 case 的信息：

在这里插入图片描述

要想面面俱到的诉说枚举中所有子项的“牵肠挂肚”，我们可以单独为每一个 case 施展“三斜杠”剑法：

/// 功法反噬总纲
///
/// 修习乾坤定数诀时可能遭遇的劫数
enum RandomError: Error {
    /// 乾坤颠倒：内力运行轨迹紊乱
    ///
    /// 多发于月圆之夜，黄历与阵仗不合时
    case random
    
    /// 逆练真经：以邪入道酿大祸
    ///
    /// 常见于强行突破数组界限的鲁莽行为
    case bad
    
    /// 天人感应：福至心灵得正果
    ///
    /// 虽名「好」实则暗藏玄机，慎之慎之
    case good
}

快看看我们的功力有没有大增，果然威力无穷：

在这里插入图片描述

3. 在 Xcode 轻松编译 DocC 文档

最后，为了将 Xcode 项目中的所有“真经”融会贯通，我们可以指示 Xcode 一次性生成全部代码的注释文档，这是通过 Product -> Build Documentation 选项命令来完成的：

在这里插入图片描述

一番等待之后，我们即可鸟瞰 Xcode 项目中所有类型、类型别名、全局方法等等你能想到任何东东的文档了：

在这里插入图片描述

从上面的演示可以清楚地看到，Xcode 甚至为我们自动创建了各个关联类型之间的链接，我们可以轻松的在它们之间反复横跳啦，棒棒哒！💯

4. 未来的憧憬

看到上面所有这些，不禁让我们产生了一丢丢“速度与激情”般的兴奋与焦躁，但是 Xcode 还可以做的更好。

随着 AI 技术的继续迅猛发展，Xcode 若能与其浑然一体那将是多么美妙的事情啊。虽然，目前 Xcode 有限制的允许我们这些秃头码农们使用 AI，但是编码体验并不非常 Nice。

我们希望 Xcode 17 的功能是：

  • 全面接入各种 AI，可在 ChatGPT、DeepSeek 等 AI 中自由选择；
  • 可以通过 MCP 向 AI 暴露自己独有的接口和方法，让程序“猿/媛”们随心所欲、直呼过瘾；
  • 可以通过 AI 代理（Agent）释放更多自由度，彻底解放秃头码农们的双手双脚；
  • 利用 AI 根据代码功能自动生成注释文档；

希望今年的 WWDC 25 可以让我们梦想成真！期待吧，么么哒！😘

总结

在本篇博文中，我们讨论了如何利用 Xcode 快捷键为项目中的代码添加文档模版，并全面编译并生成各种类型以及方法的注释。

感谢观赏，再会啦！8-)

avatar
文章
阅读
粉丝