0Pricing
Swift Academy · 课时

记录代码（DocC 入门）

编写 DocC 注释（/// 和 /** ... */），记录参数与返回值，添加示例，并为 SwiftPM 包生成静态文档。

记录代码（DocC 入门） 是 CoddyKit 上的免费 Swift Academy 课时。 这是第 3 节课，共 3 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Swift Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Swift Academy 课程共包含 3 节课。

为什么使用 DocC

DocC 会将放置恰当的注释转换为可浏览的文档网站。

  • 使用 /// 或 /** ... */
  • 说明用途，并展示一个小示例
  • 记录参数和返回值

函数文档

将 /// 直接放在声明上方。使用列表说明参数和返回值。

/// Adds two integers and returns the sum.
/// - Parameters:
///   - a: First addend.
///   - b: Second addend.
/// - Returns: The sum of `a` and `b`.
/// - Remark: Pure function; no side effects.
func sum(_ a: Int, _ b: Int) -> Int { a + b }

print(sum(2, 3)) // 5

类型与成员文档

对于类型，块注释 /** ... */ 非常实用；使用 /// 添加简短的成员文档。

/** A simple counter that tracks a running total.

 Use <code>increment()</code> to add one or a custom amount.
 
 - Note: The type is value-based (a struct).
 */
struct Counter {
    /// Current value of the counter.
    private(set) var value: Int = 0

    /// Increments the counter.
    /// - Parameter amount: How much to add (default is 1).
    mutating func increment(by amount: Int = 1) { value += amount }
}

var c = Counter()
c.increment()
c.increment(by: 3)
print("value =", c.value) // 4

示例部分

使用简短的 示例 部分。针对手机屏幕，请保持示例简短。

/// Repeats a message a given number of times.
///
/// **Example**
/// ```swift
/// repeatMessage("Hi", times: 2) // prints twice
/// ```
/// - Parameters:
///   - text: Message to print.
///   - times: How many times to print.
func repeatMessage(_ text: String, times: Int) {
    for _ in 0..<times { print(text) }
}

repeatMessage("Hi", times: 2)

构建文档

使用 SwiftPM 或 Xcode 构建文档。最好将文档保留在代码旁，这样它们会保持最新。

// Generate documentation for a SwiftPM package (examples):
//   swift package generate-documentation --target MyLib
//   swift package generate-documentation --target MyLib --output-path Docs
//
// Preview in Xcode (DocC):
//   Product > Build Documentation
//
// Tip: keep docs close to code; DocC picks up symbols with /// or /** ... */.

文档风格

提示：

  • 以一行摘要开头。
  • 描述它的功能，而不是内部实现。
  • 仅在重要时记录边界情况。
  • 简短示例优于冗长的文字说明。

DocC 注释形式

快速检查：哪些注释会生成 DocC 文档？

回顾

回顾：在符号上方编写 DocC 注释，包含参数和返回值，添加简短示例，然后通过 SwiftPM 或 Xcode 生成文档。

常见问题解答

「记录代码（DocC 入门）」课时是免费的吗？

是的 — 「记录代码（DocC 入门）」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Swift Academy 课程的其余内容，请升级到 CoddyKit PRO。 Swift Academy 课程共包含 3 节课。

「记录代码（DocC 入门）」这节课中我会学到什么？

编写 DocC 注释（/// 和 /** ... */），记录参数与返回值，添加示例，并为 SwiftPM 包生成静态文档。 你通过在浏览器中直接运行的动手代码来练习 Swift Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Swift Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Swift Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 3 节课，共 3 节。

「记录代码（DocC 入门）」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Swift Academy 课中编写并运行代码吗？

能。每节 Swift Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. SwiftFormat / SwiftLint 基础
  2. 样式指南与 API 设计指南
  3. 记录代码（DocC 入门）
← 返回 Swift Academy