Swift的DocC教程入门

HarryDeng
3,839 阅读10分钟

原文地址：DocC Tutorial for Swift : Getting Started

学习如何使用DocC为Swift自动创建文档。

版本信息：Swift 5.5, iOS 15, Xcode 13.2

在2021年之前，当苹果推出DocC时，你有两种选择来为你的Swift包写文档:你要么在项目的README中编写文档，要么使用像 Jazzy 这样的第三方库从你的代码生成文档。

Jazzy是更简单的选择，生成的文档也将与苹果官方参考文档的外观和感觉相匹配。但是如果有一种更简单的方法将你的文档直接显示在Xcode文档窗口中呢?

在WWDC 2021上，苹果推出了DocC，这是一个文档编译器来编译Swfit包的文档，也可以在Xcode文档窗口查看相应的文档。苹果在2022年WWDC大会上扩展了DocC的功能，它也可以记录Swift和Objective-C项目。

docc00.png

DocC提供了更高级的功能，比如向GitHub项目发布预构建文档，或者向应用程序文档添加目录和扩展文件。

在本教程中，你将使用一个名为 Given With Love 的应用程序来学习:

  • 使用DocC构建Swift项目和Swift包文档。
  • 使用符号连接文档中的内容。
  • 向文档添加目录。
  • 归档和发布DocC文档。
注意:本教程假设你已经熟悉使用Xcode开发SwiftUI应用程序。如果你不熟悉SwiftUI，请先查看SwiftUI: Getting Started。
笔者提示：依赖的GivenWithLoveHelper的SPM需要的 Swift tools veriosn是5.6.0，所以下载源码需要使用Xcode 14来学习本教程。

一、开始

下载初始项目 koenig-media.raywenderlich.com/uploads/202… 。在 Starter 目录下打开 GivenWithLove.xcworkspace ，然后在iPhone模拟器上构建和运行。你将看到以下屏幕:

docc01.gif

该应用展示了可用礼物的列表。选择礼物，然后输入运输信息。最后，写上收礼人的电子邮件地址。 在Xcode中，查看项目左侧的导航器。它包括以下两部分:

  • GivenWithLove (Xcodeproj):使用MVVM模式开发主工程；
  • Given With Love Helper (Swift Package):项目的助手包，如扩展或自定义视图。
注意：GientWithlove项目使用修饰符和焦点等包装器在SwiftUI中实现Focus Management，以帮助用户更有效地导航表单。

注意，有些文件中有些包含文档，有些则没有。在使用DocC构建和归档文档之前，你将留意本教程中的其他文件。

但首先，你需要了解DocC的工作原理。

二、DocC是如何工作？

DocC是一个将Markdown语言转换为富文本文档的文档编译器。

当Xcode构建你的框架时，它执行以下步骤来创建DocC文档

1、编译器保存框架上任何公共api和生成代码的详细信息。

2、编译器为DocC提供关于公共api的所有信息。

3、DocC收集公共API信息和所有其他DocC选项，如文档目录中可用的文章或教程。

4、DocC生成包含已编译文档的最终存档。

docc01.png

在下面的内容中，你将使用 *GivenWithLove* 项目去构建第一个 DocC 文档

注意：为了继续下面几节的内容，你需要回顾Markdown语言的知识，DocC将Markdown语言转换为丰富的文档。
如果你是Markdown的新手，Markdown: Syntax（https://daringfireball.net/projects/markdown/syntax）有你需要的东西。

三、构建DocC文档

使用 Xcode 打开 GivenWithLove.xcworkspace 工程。然后在菜单选择 Product ，并选择 Build Documentation。

Xcode 在几秒钟内开始构建文档，然后自动打开开发者文档窗口（也可以使用 Commad+shift+0 快速打开）。

项目文档显示在左侧的导航栏中。它包含两个部分，分别用于项目和Swift包的文档。

docc02.png

以下是在 Xcode 中构建 DocC 文档的更多选项:

Shift-Control-Command-D 快捷方式可以立即构建文档。

在 "Build Settings" 中的 "Build Documentation During ‘Build’" 的值设置为 "YES"。此选项将在每次编译时生成文档。

在CI管道或命令行中使用 "xcodebuild docbuild" 命令。这与在 "Build Settings" 中将 "Build Documentation During ‘Build’" 设置为 "YES" 的功能相同。

打开文档窗口并展开 GivenWithLove 项目查看其内容。 DocC 支持对代码进行初始分组，显示类、结构和枚举。

选择最上面的搜索字段 CheckoutViewModel 并点击，再选择第一个菜单选项。查看 DocC 如何显示其中的文档。

docc03.png

在 CheckoutViewModel 文档的描述中，点击 CheckoutData 链接

docc04.png

注意 CheckoutData 这个结构是如何没有任何文档的。此结构将是您在此项目中记录的第一个文件。

四、为Swift文件编写文档

打开 GivenWithLove.xcworkspace 工程，然后选择打开 CheckoutData.swift 。Command 点击 CheckoutData 可以打开操作菜单。接下来，单击选择 Add Documentation，Description 占位符出现在结构声明的上方，在三个反斜杠之后。现在，您可以编写这个结构的文档了。

docc05.png

还有一个快捷键，你可以将光标放在 CheckoutData 上，并按下 Command+Option+/ 或者在上方的行中输入 ///。

用下面的代码替换 Description 占位符:

Checkout data needed to send a specific gift to a recipient's address and a gift message to the recipient's email.

这段代码生成的描述将出现在 Documentation 窗口中的 CheckoutData 下面。

构建文档（Shift + Control + Command + D）后，选择CheckoutData，你应该会看到刚刚添加的描述。

docc06.png

选择顶部的搜索字段并输入 Validation，然后选择标题 Workspace Documentation 下的选项： docc07.png

新打开的文件是 Given With Love Helper Swift 包中的一个枚举。注意，除了第一个方法之外，枚举中的所有方法都有对应的文档注释。现在来给第一个方法进行文档注释：

docc08.png

在 Given With Love Helper Swift 包中打开 Validation.swift 。将光标放在第一个方法上，然后按 Command+Option+/。Xcode 会显示此枚举的可用文档占位符，如 Description、Parameters和Returns。

用下面的代码替换占位符：

/// Check if the input string is valid compared to the specified regex.
/// - Parameters:
///   - input: Input string under test.
///   - regex: The regex that compared to the input string.
/// - Returns: True if the input string is valid compared to the specified regex and false otherwise.

这段代码描述了该方法的每个细节。当它的输入字符串与它的输入正则表达式匹配时，它返回true。

通过将方案更改为 GivenWithLoveHelper 并按 Shift-Control-Command-D 来构建文档。

在 Xcode 文档窗口，从侧导航器展开 GivenWithLoveHelper ，然后选择 Validation enum 。查看上述文档是如何出现在此枚举的第一个方法下的：

docc09.png

单击 isValid(input:with:) 并查看它如何包含完整的详细信息：

docc10.png

现在，你知道了如何使用 DocC 创建文档。接下来，你将学习向文档添加一个引用，该引用可以是文档内的，也可以是文档之外的内容。

五、使用符号链接

打开 GivenWithLove.xcworkspace 工程，然后打开 CheckoutData.swift。用下面的代码替换 CheckoutData 上面的当前文档:

/// Checkout data needed to send a specific ``Gift`` to a recipient address and giftMessage to ``RecipientEmail``.

双反勾语法为 Gift和 RecipientEmail 结构创建了一个链接，苹果称这些链接为符号链接。

注意：当你写双反勾（``），然后开始输入结构名时，Xcode显示从你的项目文件中自动完成的建议。

docc11.png

构建文档，选择 CheckoutData 并检查上面的描述如何显示在它下面，这两个符号以链接的形式出现在文档中，分别可以打开文档页面：

docc12.png

打开 GiftMessageView.swift，然后在 GiftMessageView 的上一行添加以下注释:

/// Gift message view including ``CheckoutData/giftMessage`` that user send to ``CheckoutData/recipientEmails``.

这个注释为 GiftMessageView 添加了文档。

注意，你在这里引用了不同结构的属性，因此你专门用它的结构名来拼接它，例如 CheckoutData/giftMessage，你可以通过 command 点击 这些链接来导航到正确的文件。

构建文档，从侧导航器中选择 GiftMessageView 并检查上述符号在其文档中的显示方式。

docc13.png

现在，您已经熟悉了 DocC 的要点。是时候进入下一阶段了。

六、更加丰富的应用文档

DocC 文档提供了许多选项使其更有趣，以下是一些例子:

  • 目录：向文档中添加更多内容或自定义符号链接。
  • 文章：向用户展示框架背后的整体。您可以使用插图来显示框架的平台页面，提供一个概要给使用文章的人阅读。
  • 教程：从头开始制作交互式指南，向用户介绍您的框架。这些文档引导用户逐步进入您的框架，比参考文档或文章更深入。
  • 扩展文件：使用标记文件来帮助您安排任何符号属性和方法，或覆盖源文档中的注释。

是时候改进你的文档了，在下一节中，您将学习如何向 DocC 文档添加目录。

文档的目录

Xcode 中右键单击 GivenWithLove 文件夹，然后选择 New File… 再选择 Documentation Catalog，然后单击Next，将目录命名为GivenWithLoveCatalog，然后单击 Create。 GivenWithLoveCatalog 文档目录出现在 GivenWithLove 项目中。

选择并打开 GivenWithLoveCatalog.md 文件和检查出现在其中的占位符。用下面的代码将目录中的以下内容替换为文本占位符:

# ``GivenWithLove``

The app displays a list of available gifts. Select a gift, then enter shipping information. Finally, write a gift message along with the recipient's email addresses.

## Overview

Through this app, you'll learn all about focus management in SwiftUI using modifiers and wrappers like **FocusState** to help users navigate forms more effectively.

You'll learn how to:
- Use the **FocusState** property wrapper with both the **focused(_:)** and **focused(_:equals:)** modifiers.
- Manage focus in lists and with the MVVM design pattern.
- Use the **FocusedValue** and **FocusedBinding** property wrappers to track and change the wrapped values of focused views from other scenes.

这段代码在目录中创建了 GivenWithLove 项目的摘要和概述文档。

构建文档并选择 GivenWithLove ，注意新添加的目录如何显示为项目文档标题下的更多内容：

docc14.png

打开 GivenWithLoveCatalog.md, 并用下面的代码替换 Topics 下面的文本:

## Topics

### Model

- ``CheckoutData``
- ``Gift``

这段代码在目录中的 Topics 下添加了一个组，以显示模型及其符号。在这里，您使用目录自定义项目符号的组织。

构建文档并再次选择 GivenWithLove 。在文档窗口的 Topics 下检查新添加的组：

docc15.png

现在，您有机会按照你认为合适的方式继续定制这个目录。你还可以在 GivenWithLoveHelper Swift 包中添加另一个目录，以向其文档添加内容。

太棒了！你已经完成了文档的开发，可以准备对文档进行归档和发布了。

docc16.png

七、导出和发布文档

首先，将鼠标移到文档窗口的导航器侧。当您将鼠标悬停在 GivenWithLove 框架项上时，会出现一个上下文菜单图标。单击它，然后单击 Export 。将存档保存到您的桌面：

docc17.png

现在，你可以把它发送给你的同事，如果他们双击存档，它会在 Xcode 的文档窗口中打开。

八、何去何从?

下载最终项目 koenig-media.raywenderlich.com/uploads/202… 。检查 Given With Love 应用的 final 版本，并将其与你的版本进行比较。

现在您已经知道了如何使用 DocC 编写文档，接下来可以进一步改进文档。查看“提高Swift-DocC内容的可发现性”。本文将帮助您更好地组织文档，确定其主题，并给出清晰、独特的标题。

如果希望自定义文档的登录页或在扩展文件中排列嵌套符号，请查看 向文档页面添加结构。

最后，要了解更多关于配置您的web服务器来托管生成的DocC归档文件和学习如何自动化文档生成的信息，不要错过 host和自动化您的DocC文档。

在使用 DocC 生成丰富的文档时，请记住编写干净代码的价值。根据 Steve McConnell 的说法:

“Good code is its own best documentation. As you’re about to add a comment, ask yourself, “How can I improve the code, so this comment isn’t needed?” Improve the code and then document it to make it even clearer.”

“好的代码本身就是最好的文档。当您准备添加注释时，问问自己，“我怎样才能改进代码，使此注释不再需要?”改进代码，然后重写文档，使其更加清晰。”

avatar
文章
阅读
粉丝