用途
Swift DocC 用于为 Swift 代码编写和组织文档。它把源码中的 /// 注释与 .docc 目录文件编译成可导航的层级结构:落地页 → 文章 → 符号页。其中 ## Topics 分组决定符号在层级中的位置——没有它,DocC 仍会渲染符号,但导航树中不会有任何链接指向它。
主要能力
- 为单个符号编写文档:在源码文件中使用 /// 块。
- 将多个符号组织到某个类型下:在类型上使用带 ## Topics 的 /// 块。
- 在不改动源码的情况下添加 Topics:在目录中使用扩展 .md 文件。
- 编写模块概览或概念指南:创建带落地页文章的 .docc 目录。
- 编写分步教程:使用 .tutorial 文件。
使用方式
第一步:确定范围
先明确要产出哪种输出:文档化单个符号、在类型下组织多个符号、通过扩展文件添加 Topics、编写模块概览或概念指南,还是编写分步教程。在动笔前先确定输出类型。
第二步:编写符号文档
只使用 ///(三斜线),不要使用 /** */。注释必须紧邻声明,中间不能有空行。
/// One-sentence abstract describing what this does.
///
/// Extended discussion — one or more paragraphs. Markdown works here:
/// **bold**, _italic_, `inline code`.
///
/// > Note: Appears as a blue callout. Also: Warning, Important, Tip, Experiment.
///
/// Link symbols with double backticks: ``OtherType`` or ``OtherType/method(_:)``.
/// Link articles with: <doc:ArticleName>.
///
/// ```swift
/// let result = try client.fetch(request)
/// ```
///
/// - Parameters:
/// - paramName: What this parameter represents.
/// - another: Another parameter.
/// - Returns: What the return value represents (omit if obvious from the abstract).
/// - Throws: ``MyError/notFound`` when the resource does not exist.
public func fetch(_ request: Request) throws -> Response { ... }
规则:
- 摘要(abstract)是第一条非空 /// 行,会出现在对该符号的每次引用中。
-
- Parameters: 的子项缩进两个空格: - name: description。
-
- Returns: 仅在返回值提供摘要之外的信息时使用。
-
- Throws: 仅在方法可能抛出错误时使用,并逐一列出错误情况。
- 属性和枚举 case 只需摘要,跳过 Parameters/Returns。
- 不要使用 @param、@return、@throws——那是 Objective-C javadoc 风格。
完成标准:范围内每个公开符号都有摘要;带参数的方法有 - Parameters: 块;所有抛出的错误都列在 - Throws: 下。
第三步:添加 Topics 构建层级
没有 ## Topics 部分时,类型的成员会出现在其页面上,但不会出现在导航侧边栏或文章链接中。Topics 可以内联写在源码里,也可以写在扩展文件中。
内联(写在类型本身上):
/// The main networking client.
///
/// ## Topics
///
/// ### Creating a Client
/// - ``init(configuration:)``
///
/// ### Making Requests
/// - ``fetch(_:)``
/// - ``upload(_:data:)``
public struct NetworkClient { ... }
扩展文件(.docc 目录中的 NetworkClient.md):
# ``NetworkClient``
@Metadata {
@DocumentationExtension(mergeBehavior: append)
}
## Topics
### Creating a Client
- ``init(configuration:)``
### Making Requests
- ``fetch(_:)``
- ``upload(_:data:)``
mergeBehavior: append 会在不改动源码内摘要的情况下添加 Topics;mergeBehavior: override 会完全替换源码内文档。
完成标准:每个拥有子符号的类型都有 ## Topics 部分,并在命名分组下列出所有公开成员。
第四步:创建文档目录(需要时)
目录是放在 Sources/ModuleName/ 内的 ModuleName.docc 文件夹:
Sources/Auth/Auth.docc/
├── Auth.md ← landing page
└── Resources/ ← images, videos (optional)
落地页(Auth.md):
# Auth
@Metadata {
@TechnologyRoot
}
One-sentence module summary.
## Overview
One or more paragraphs introducing the module.
## Topics
### Essentials
- ``AuthClient``
- ``AuthClientConfiguration``
### Session Management
- ``Session``
- ``User``
@TechnologyRoot 将其标记为模块根。没有它,DocC 可能不会在 Xcode 或 Web 输出中把它渲染为顶层入口。
完成标准:目录文件夹存在,且落地页编译无警告。
第五步:验证
./scripts/test-docs.sh
如果 ./scripts/test-docs.sh 不可用:
swift package generate-documentation --target ModuleName 2>&1 | grep -E "warning:|error:"
在宣布完成前修复所有警告。完成标准:文档构建以 0 退出且无警告。
常见错误
- 使用 /** */ 而非 ///:改为每行使用三斜线。
- 注释与声明之间有空行:删除空行,不允许有间隔。
- 使用 @param、@return、@throws(Obj-C 风格):改用 - Parameters:、- Returns:、- Throws:。
- 用单反引号做符号链接
Foo:改用双反引号Foo。 - 符号未出现在导航侧边栏:添加指向它的 ## Topics 条目。
- 落地页缺少 @TechnologyRoot:添加 @Metadata { @TechnologyRoot }。
- 扩展文件标题使用纯文本 # NetworkClient:改用符号路径 #
NetworkClient。 - doc:Article 链接无法解析:检查文章文件名是否完全匹配(区分大小写)。
元数据指令参考
- @TechnologyRoot:将落地页标记为模块根。
- @DocumentationExtension(mergeBehavior: append):追加到现有符号文档。
- @DocumentationExtension(mergeBehavior: override):替换现有符号文档。
- @DisplayName("Custom Name"):覆盖符号名在导航中的渲染方式。
- @PageKind(sampleCode):将页面标记为示例代码。
符号链接路径语法
TypeNameTypeName/propertyNameTypeName/methodName()TypeName/methodName(_:secondLabel:)TypeName/init(label:)
适用场景
适用于为 Swift 包或模块编写 API 文档、组织符号导航层级、创建模块概览与概念指南,以及编写分步教程。
限制
资料未提供关于收费、价格、平台支持范围或具体效果的信息。