跳转至

Swift的DocC教程：入门

2022年9月20日，Swift 5.5，iOS 15，Xcode 13

了解如何使用DocC自动为Swift创建文档。作者：Mina H.Gerges。

下载材料

了解如何使用DocC为Swift自动创建文档。

在2021年苹果推出DocC之前，你有两个选择来记录你的Swift包。你要么把文档写在项目的自述文件中，要么使用第三方库，如 Jazzy 从你的代码中生成文档。

Jazzy是比较简单的选择，而且生成的文档也符合苹果官方参考文档的外观和感觉。但是，如果有一种更简单的方法可以将你的文档直接显示在Xcode文档窗口中呢？

在WWDC 2021上，苹果推出了DocC，一个文档编译器，可以在Xcode文档窗口内构建和查看你的Swift包的文档。苹果在WWDC 2022中扩展了DocC的功能，所以它也可以记录Swift和Objective-C项目。

A meme picture of a guy talking about creating a documentation document so you could have documentation of your documentation.

DocC提供了更多的高级功能，例如将预建的文档发布到GitHub项目中，或者将目录和扩展文件添加到应用文档中。

在本教程中，你将在一个名为Given With Love的应用程序上工作，以了解。

  • 使用DocC构建Swift项目和Swift包的文档。
  • 使用符号来连接文档中的项目。
  • 为你的文档添加一个目录。
  • 归档和发布DocC文档。

Note

本教程假定您对使用Xcode开发SwiftUI应用程序感到满意。如果您不熟悉SwiftUI，请先查看 SwiftUI: Getting Started。你需要安装Xcode 13来学习本教程。

开始

点击本教程顶部或底部的下载材料按钮，下载启动项目。在Xcode的starter目录下打开GivenWithLove.xcworkspace。在iPhone模拟器上建立和运行。你会看到下面的屏幕：

A demo for the Given With Love app displays a list of available gifts. User selects a gift, proceeds to the checkout process.

该应用程序显示一个可用的礼物列表。选择一个礼物，然后输入运输信息。最后，写一个礼物信息和收件人的电子邮件地址。

在Xcode中，看一下项目导航器。它包括这两个部分。

  • GivenWithLove（Xcodeproj）：使用MVVM模式的主要项目文件。
  • Given With Love Helper（Swift Package）：项目的帮助包，如扩展或自定义视图。

Note

GivenWithLove项目在SwiftUI中使用修改器和包装器（如FocusState）实现焦点管理，以帮助用户更有效地浏览表单。

要了解更多关于在SwiftUI中处理焦点管理的信息，请查看SwiftUI中的焦点管理：入门。

注意这些文件中有些包含了文档，而有些则没有。在使用`DocC构建和归档文档之前，你将在本教程中记录其余文件。

但首先，你需要了解DocC是如何在引擎盖下工作的。

DocC如何工作

DocC是一个文档编译器，可以将Markdown语言转化为丰富的文档。

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

  1. 编译器保存关于您的框架和生成的代码上的任何公共API的细节。
  2. 编译器提供DocC所有关于你的公共API的信息。
  3. DocC收集公共API信息和所有其他DocC的选项，如文章或教程与你的文档目录。
  4. DocC产生包含编译后的文档的最终存档。

Flowchart shows the Xcode steps to create DocC documentation

在下一节，你将在GivenWithLove应用程序中建立你的第一个DocC文档。

Note

为了跟进接下来的章节，你需要回顾一下你对Markdown语言的知识，DocC将其转化为丰富的文档。

如果你是Markdown的新手，Markdown: Syntax有你需要的东西。

构建DocC文档

打开GivenWithLove.xcworkspace。打开Product菜单，选择Build Documentation。

Xcode开始构建文档，持续几秒钟，然后打开开发者文档窗口。

项目的文档出现在左边的导航器上。它包含项目和Swift包文档的两个部分。

Preview of the GivenWithLove DocC documentation.

这里有一些在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如何显示里面的文档。

Preview of the CheckoutViewModel DocC documentation.

在CheckoutViewModel描述中，点击CheckoutData链接。

Two screenshots showing how to navigate from CheckoutViewModel to Checkout Data inside documentation

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

记录一个Swift文件

打开GivenWithLove.xcworkspace，然后是CheckoutData.swift。命令点击CheckoutData来打开动作菜单。接下来，点击Add Documentation。在三个反斜线之后，Description占位符出现在结构声明的上方。现在，你已经准备好编写这个结构的文档了。

CheckoutData action menu showing add documentation button.

也有一个键盘快捷键用于此。你可以把光标放在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.

这段代码产生的描述将出现在文档窗口中CheckoutData下面。

建立文档。选择CheckoutData，你应该看到你刚刚添加的描述。

CheckoutData before and after adding the description

选择上面的搜索栏，输入Validation，然后选择标题下的选项Workspace Documentation。

DocC window displays the options available for validation search query.

新打开的文件是Given With Love Helper Swift包内的一个枚举。注意这个枚举里面的所有方法都被记录下来了，除了第一个方法。你现在要把它记录下来。

Preview of Validation enum documentation with the first method undocumented.

打开Given With Love Helper Swift包内的Validation.swift。把光标放在第一个方法上，然后按Command+Option+/。Xcode会显示这个枚举的可用文档占位符，如描述、参数和回报。

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

/// 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.

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

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

从侧面导航器中展开GivenWithLoveHelper，然后选择Validation枚举。请看上面的文档是如何出现在这个枚举的第一个方法下的。

Preview of Validation enum documentation in Documentation window.

点击isValid(input:with:)，看看它如何包含完整的细节。

Preview of isValid method documentation in documentation window

现在，你知道如何使用DocC创建文档。接下来，你将学习如何为一个属于你的文档或位于文档之外的文档添加一个引用。

应用符号链接

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

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

双重回车键语法为Gift和RecipientEmail结构创建一个链接。苹果将这些链接称为symbol links。

Note

当你写下双回车键，然后开始输入结构的名称时，Xcode会显示你的项目文件的自动完成建议。

Auto complete while typing the symbol name in Xcode documenation.

建立文档。选择CheckoutData，检查上面的描述如何出现在它下面。这两个符号在文档中以链接的形式出现，打开各自的文档页面。

Preview of CheckoutData in documentation with symbol links

打开GiftMessageView.swift，然后在GiftMessageView前一行添加以下注释：

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

这条评论为GiftMessageView添加了文档。

Note

你在这里引用了一个不同结构的属性，所以你专门用它的结构名称来写，比如CheckoutData/giftMessage。你可以通过命令点击这些链接来导航到正确的文件。

建立文档。从侧面导航器中选择GiftMessageView，并检查上述符号在其文档中是如何出现的。

Preview of GiftMessageView documentation with symbols of a different parent

现在，你已经熟悉了DocC的基本原理。现在是时候进入下一个层次了。

丰富应用程序的文档

DocC的文档提供了许多选项，使其更加有趣。这里有几个例子：

  • Catalog：为你的文档添加更多的内容或自定义符号的组织。
  • Articles：向用户展示你的框架背后的大图片。你可以用一个插图来展示你的框架的登陆页面，用articles来提供你的软件包的摘要。
  • Tutorials：从头开始制作互动指南，向用户介绍你的框架。这些引导用户一步步进入你的框架，比参考文档或文章更深入。
  • Extension Files：使用标记文件，帮助你安排任何符号属性和方法或覆盖源文件中的注释。

现在是改善你的文档的时候了。在下一节中，你将学习如何在你的DocC文档中添加一个Catalog。

文档目录

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

选择名为GivenWithLoveCatalog.md的内部文件，检查其中出现的占位符。用下面的代码替换目录下的Text占位符里面的内容：

# ``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。注意新添加的目录是如何在你的项目文档标题下出现更多内容的。

Preview of GivenWithLove catalog inside documentation

打开GivenWithLoveCatalog.md，用下面的代码替换Topics下的文字：

## Topics

### Model

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

这段代码在你的目录中的Topics下添加了一个组，以显示Models和它们的符号。在这里，你使用目录来定制你项目的符号组织。

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

Two screenshots showing topics of GivenWithLove without and with model documentation.

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

好啊! 你已经完成了文档的编写，准备好归档和发布你的文档了。

Lord of the Rings series hero saying the documentation is finally done

导出和发布文档

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

Preview of GivenWithLove Documentation showing export button to archive documentation

现在，你已经准备好把它发送给你的同事了，如果他们双击存档，它将在Xcode的文档窗口中打开。

接下来去哪？

点击本文顶部或底部的下载材料按钮。检查Given With Love应用程序的最终版本，并将其与您的版本进行比较。

现在你知道了如何使用DocC进行记录，你可以更进一步，改进你的文档。请查看提高您的Swift-DocC内容的可发现性。这篇文章将帮助你更好地组织你的文档，确定其主要主题，并赋予其清晰、独特的标题。

如果您想定制您的文档的登陆页面或安排扩展文件中的嵌套符号，请查看为您的文档页面添加结构。

最后，要了解更多关于配置你的网络服务器来托管生成的DocC档案，以及学习如何自动生成文档，不要错过托管和自动生成DocC文档。

在使用DocC生成丰富的文档时，请牢记编写干净代码的价值。根据Steve McConnell的说法"好的代码是它自己最好的文档。当你要添加注释时，问问自己，"我怎样才能改进代码，使这个注释不需要？" 改进代码，然后把它记录下来，使之更加清晰。"

加入下面的讨论，提出问题，提供建议，甚至分享你为改进这个项目所做的事情。