【老司机精选】DocC: 未曾设想的苹果文档

作者：旷明，iOS Dev。GitHub: KeithBird Twitter: @KeithBirdKTH Blog: Kth App: 语法树

审阅：示晔，iOS 开发。Swift 和 NodeJS 爱好者

本文根据 Session 10166 10167 10235 10236 梳理

作者将本教程和部分 WWDC 中的代码实践，经过 DocC 技能编译成教程放在 WWDocC 代码库中

前语

苹果在 WWDC 视频上投入的精力众所周知，但留给开发者的官方文档常常惨不忍睹，甚至于有一个专门的网站统计了 No Overview Available 的苹果文档。据调查只要 30% 左右的 iOS 开发者经过官方文档学习 API，Paul Hudson 也在 WWDC 21 前许愿写下 Reimagining Apple’s documentation 一文。

但 SwiftUI Tutorials 和 Catalyst Tutorials 仍然好像两股清流，是开发者们在文档沙漠中的绿洲。苹果很明显没有时刻为每项技能供给如此生动的教程，于是将这个才干经过 DocC (Documentation Compiler) 开放给了开发者们（和 iPad 没有计算器有异曲同工之妙）。当然 DocC 也能够用来给自己的开源项目编写文档，以加速项目的推行和建造。

文档的编译

DocC 经过编译源码中的文档注释和 DocC 专属的文档文件生成文档的文本内容。文本内容经过咱们接下来要编写的链接，和源码编译后提取的接口结构，安排在一起，构成终究的文档。

经过点击菜单栏的 Product > Build Documentation 能够完结编译。也能够将此过程增加到 Build 过程中，只需在 Building Settings 的 Documentation Compiler 中，将 Build Documentation during ‘Build’ 设为 Yes。想了解如何运用命令行编译，能够检查「文档的发布」一节。

编译文档注释

Xcode 首要会编译代码源文件，并提取文档注释中的公共 API 信息（如概要、参数阐明、返回值阐明等)，以生成一些文档内容，作为生产 DocC Archive 的部分材料。因此，在默许情况下，DocC 仅靠编译源码，就能够生成按接口类型和接口结构安排的文档。

编译文档文件

当你有如下需求时，能够考虑运用 documentation catalog 为文档注释进行弥补：

• 经过文档主页介绍结构和首要接口。
• 需求自定义安排文档的结构。
• 经过文章详细阐明开源结构。
• 经过教程逐渐辅导最佳实践。
• 文档中包括图片视频等内容。

你能够新建一个 documentation catalog，将其放到 Swift package 中与源码相同的目录下。也能够在新建 Swift framework project 时，勾选 Include Documentation。

DocC 将会结合 Swift compiler 中的公共 API 信息，和 documentation catalog 中的文档内容，以生成愈加丰厚的 DocC Archive 文档文件。

注释的格局

按住 Command 键点击接口称号并选择 Add Documentation 能够主动生成文档注释的模版。你能够在模版中顺次填写接口的概要、阐明、参数阐明、返回值阐明、抛出阐明等内容。这些内容的编写格局为 markup，markup 会在文档的编写中多次运用，能够在 Formatting Your Documentation Content 一文中进行学习。

/// Eat the provided specialty sloth food.
///
/// Sloths love to eat while they move very slowly through their rainforest 
/// habitats. They're especially happy to consume leaves and twigs, which they 
/// digest over long periods of time, mostly while they sleep.
///
/// When they eat food, a sloth's `energyLevel` increases by the food's `energy`.
///
/// - Parameters:
///   - food: The food for the sloth to eat.
///   - quantity: The quantity of the food for the sloth to eat.
///
/// - Returns: The sloth's energy level after eating.
///
/// - Throws: `SlothError.tooMuchFood` if the quantity is more than 100.
mutating public func eat(_ food: Food, quantity: Int) throws -> Int {...}

经过编写上面的文档注释并进行编译，你能够在对应的接口文档中看到以下信息：

也能够经过 Quick Help (optiong + 点击接口名弹出) 检查：

文档的编写

DocC 中的文档总共分为三类：在官方文档中被普遍运用，用于详细介绍接口的参阅文档（Reference）。形式愈加灵活自在，用于介绍结构背面结构（如不同组件之间的联系）的文章（Articles）。经过交互式的逐渐辅导，协助用户完结最佳实践的教程（Tutorials）。

咱们首要从参阅文档中的主页开端：

编写内容

默许情况下，DocC 会经过列出公共接口，并按类型进行分组来构成主页，作为文档的入口。

但咱们也能够经过以下过程进行自定义。首要所有 DocC 文件有必要在与项目同名的 documentation catalog 中才有效，咱们能够在其间新建一个 Documentation 中的 Empty 文件作为主页：

相同用项目名给这个 .md 文件重命名，且标题 ```` 中的内容也要是项目名，这样 Xcode 才干在编译时将它们相关起来。标题下方是一段概要，接着你能够用 markup 语法为文档的主页增加文字、代码、图片、视频等内容。

# ``SlothCreator``
Catalog sloths you find in nature and create new adorable virtual sloths.

重写结构

在咱们刚刚编写的文档内容之后，你会发现公共接口默许按类型罗列在 Topic 主题中，假如你期望按照自己的主意重新安排，能够在主页文件中追加 Topic 部分：

其间 ### 用于给每个分组命名。- <doc:/tutorials/SlothCreator> 用于链接 tutorials 目录下名为 SlothCreator 的文件。```` 用于链接到对应的接口文档，其内容有必要是接口的完整途径，如 ``SlothCreator/Sloth/eat(_:quantity:)``。

Topics 被重构后，能够发现左侧导航栏的结构也随之改动：

假如自行编写的 Topics 中遗漏了部分公共接口或 DocC 的文章和教程目录等，它们依旧会以默许（按类型分组）的方法追加到自定义的结构之后，以保证文档的完整性。

除了主页能够自定义，各个接口的参阅文档相同能够自定义。只需新建一个 Documentation 中的 Extension File，将文件名改为接口名，并在第一行 ```` 中填写接口的完整途径。文档内容和 Topics 的编写方法与主页相同，它们会被增加到文档注释生成的文档内容之后。

# ``SlothCreator/Sloth``
## Topics
### Creating a Sloth
- ``init(name:color:power:)``
- ``SlothGenerator``
...

需求留意的是标题 # 后面的 ```` 用于给 Xcode以提示：对应的接口名需求被链接到本篇文档。正文中 - 后面的 ```` 用于发生一个链接以跳转到对应的接口文档。接口内部的成员假如没有被完整列出，也会像主页一样按默许方法追加到末尾。

掩盖注释

Extension File 中的内容默许会追加到文档注释编译生成的内容之后，但在某些时分咱们期望完全重写参阅文档，这时咱们需求在标题下方注明选用掩盖方法：

# ``SlothCreator/Sloth``
@Metadata {
    @DocumentationExtension(mergeBehavior: override)
}

此处内容会掩盖源码生成的概要。
## Overview
此处内容会掩盖源码生成的综述。
...

留意，这一参数的改动并不会影响 Topics 中的内容。

弥补性文章

文档以接口为标题进行编写，结构相对死板。而文章则是一种愈加灵活的方法，能够对结构的其他方面进行弥补阐明。你能够经过新建一个 Documentation 中的 Article File 来创立文章。

文章默许会作为结构中的最顶层出现在主页和导航栏中。因此，与咱们之前编写的内容不同的是，文章的标题是惯例内容而不是引证。对应的，其文件名也没有特殊要求，只要在该文章被引证时才会用到。文章的正文内容相同运用 markup 进行编写，相同能够在末尾追加 Topics 以安排文档结构。

# Getting Started with Sloths
Create a sloth and assign personality traits and abilities.
## Overview
Sloths are complex creatures that require careful creation and a suitable
habitat.
...
## Topics
### Essentials
- <doc:/tutorials/SlothCreator>
- ``Sloth``

交互式教程

交互式教程的作用难以言传，没有体验过的读者能够参阅 SwiftUI Tutorials 和 Catalyst Tutorials。教程一起也是 DocC 中的一大亮点，它首要由教程目录和教程页两部分组成：

文件格局

教程需求被建立在 documentation catalog 之中。你能够经过新建 Documentation 中的 Tutorial Table of Contents 和 Tutorial File 来创立教程目录和教程页，它们都是 .tutorial 文件。只要教程目录能跳转到教程页，所以即使只要一个教程也有必要编写教程目录。默许情况下 documentation catalog 会包括一个 Resources 文件夹，用于储存 DocC 的文档、文章、教程中所运用到的图片、视频、代码等资源。

如图所示，markup 文件中运用的图片有官方的命名主张：

其间只要图片名和拓宽名为必选项，~dark 表示在暗黑模式下会运用该图片，@ 之后所接的内容用于标明不同显现份额的设备所运用的图片。选用上述命名方法，只需在 markup 文件中填写图片名，DocC 便会主动在文档中动态选用最佳版别的图片。[ ] 中是对图片内容的描绘，用于给视障人士供给语音提示。

![A sloth hanging off a tree.](sloth)

代码资源没有官方命名规范，因为其首要用在逐渐教程中，主张将其命名为 教程名-章节名-过程数.swift。

目录编写

在新建教程目录后 Xcode 会主动填写模版，以协助开发者入门。目录文件名和 @Tutorials(name: ) 中的内容一般为项目名。

@Intro 指令后紧接着目录的标题，教程的概述，和一张封面图片。预计用时和 Get Started 按钮是根据之后供给的教程页信息主动生成的。

@Chapter 指令用于分类和安排教程，包括了篇名，篇目图片，教程引证。其间 @TutorialReference 能够用文件名链接到对应的教程页。

一个教程目录（@Tutorials）包括一个介绍（@Intro）和多个篇目（@Chapter），一个篇目又能够包括多个教程页的引证（@TutorialReference）。

教程编写

一个教程页（@Tutorial）包括一个介绍（@Intro）和多个章节（@Section），一个章节只能包括一个过程集（@Steps），过程集之下的过程（@Step）是最小的结构。

教程页的文件名没有特殊要求，仅在链接时运用。@Tutorial(time: ) 中填写阅读该教程页的预计用时。该教程所处的篇目名（SlothCreator Essentials）会主动显现。教程页 @Intro 的格局和目录的一样。

教程页下的结构为章节（@Section）。章节用 @ContenAndMedia 来显现简介，并且能够经过填写 (layout: ) 中的参数，调整图片等媒体与文字内容的排版方法。

@Step 中包括一段在左边逐渐展示的阐明，开发者期望文档中显现的文件名，代码段真实的文件名，和一张预览图：

能够看出预览图并非代码编译生成的，需求开发者提前截图保存。主张将源码文件和预览图片规范命名，并分组放到之前提到的 Resource 文件夹中，避免发生混乱。

@Code 并不是有必要的，@Step 也能够写成这样：

@Step {
    Create a new project using the iOS App template.

    @Image(source: image-Tutorial1-Section1-Step1.png, alt: "")
}

作用如下：

需求留意的是 @Image(source: image.png, alt: "") 中的 alt 参数是不能够省掉的，上面的图片中的示例代码因为缺少该参数会被 Xcode 报错。alt 的全称是 alternative text，这段文字将会被读屏器 VoiceOver 朗诵，用于给视障人士供给协助。

文档的发布

Xcode 编译完文档之后会发生一个 documentation archive 文件，你能够将该文件直接从文档中导出：

也能够运用命令行东西编译到指定地址：

xcodebuild docbuild
    -scheme SlothCreator
    -derivedDataPath ~/Desktop/SlothCreatorBuild

在编译过程中，Xcode 会在方针地址生成数量众多的文件，能够运用下面的指令进行定位：

find ~/Desktop/SlothCreatorBuild
    -type d -name '*.doccarchive'

只需将 .doccarchive 文件包发送给其他开发者，对方就能够用 Xcode 将其打开以检查文档。文件包中首要含有 css、html、js、文档、图片、视频等内容：

因为文件中包括有用于呈现文档内容的 HTML，开发者甚至能够将文档保管到网站上。下面以 Apache 为例，解说将文档保管到网站上所需的过程：

1. 将 .doccarchive 文件复制到服务器用于供给文件的目录。
2. 在服务器上增加一条规矩将以 /documentation 或 /tutorials 最初的 URL 路由到 index.html。
3. 再增加一条规矩以支撑拜访文件中的 CSS 和图片等资源。

为了定位到文档，参阅文档和文章的 URL 需求以 /documentation 最初，教程的 URL 需求以 /tutorials 最初。举例来说，假如需求定位到 SlothCreator 文档中一个名为 SlothGenerator 的协议，URL 如下：

https://www.example.com/documentation/SlothCreator/SlothGenerator

以下是 .htaccess 文件中装备的内容：

# Enable custom routing.
RewriteEngine On
# Route documentation and tutorial pages.
RewriteRule ^(documentation|tutorials)\/.*$ SlothCreator.doccarchive/index.html [L]
# Route files within the documentation archive.
RewriteRule ^(css|js|data|images|downloads|favicon\.ico|favicon\.svg|img|theme-settings\.json|videos)\/.*$ SlothCreator.doccarchive/$0 [L]

苹果许诺将在今年内开源 DocC，一起发布一个能够保管非官方文档的应用程序，到时即使不必 Xcode 也能够享受 DocC 的文档工作流程，以上杂乱的装备过程也将得到简化。

跋文

「Talk is cheap, show me the code」的年代现已过去，一份生动的文档不仅能为开源结构如虎添翼，相同也是降低沟通成本和遍及新技能的利器。随着互联网公司的体量越来越大，技能文档浩如烟海，办理起来如海底捞针，不禁成为团队协作的一大障碍。DocC 是苹果供给的新方案，在可预见的未来，无论是科技公司、开源社区还是 IT 教育机构，都将着手经过这一技能优化自己的文档办理方法，为程序员间的技能交流建立更高效的基础设施。

重视咱们

咱们是「老司机技能周报」，一个持续寻求精品 iOS 内容的技能大众号。欢迎重视。

重视有礼，重视【老司机技能周报】，回复「2021」，收取 2017/2018/2019/2020 内参

支撑作者

在这里给我们推荐一下 《WWDC21 内参》 这个专栏，总共有 102 篇关于 WWDC21 的内容，本文的内容也来源于此。假如对其他内容感兴趣，欢迎戳链接阅读更多 ~

WWDC 内参 系列是由老司机牵头安排的精品原创内容系列。 现已做了几年了，口碑一直不错。 首要是针对每年的 WWDC 的内容，做一次精选，并号召一群一线互联网的 iOS 开发者，结合自己的实践开发经验、苹果文档和视频内容做二次创造。