认识 Xcode 中的 DocC 文档

探索如何使用 DocC 构建和共享适用于 Swift 软件包和框架的文档。我们将展示如何从您自己的代码或您依赖的第三方代码开始生成文档，并使用 Markdown 编写和设置格式。我们还将带您了解导出流程，帮助您生成 DocC 存档，进行公开分享。

资源

相关视频

WWDC23

使用 Swift-DocC 创建丰富的文档

WWDC21

下载

嗨我是维多利亚我在文档工具团队担任工程师在Apple这里我和我的同事伊森将向你介绍 Xcode 13中新的文档功能新的读取和编写文档方式会与您的作业流程契合并为您的发展开启新的可能性 Xcode 13的新功能适用于Swift框架和软件包去构建、编写和浏览文档它开启了一个强大的文档驱动开发模式当您在编写程序代码的时候您可以读取所有关于您的Swift依赖项这文档就在Xcode里开发者文档窗口中的平台库旁边在这次议程我们将概述 Xcode 13里的文档功能为您详细地解释如何在您正编写和使用的 Swift框架和软件包去构建文档并向您示范如何使用Xcode 13 去编写出色的文档然后通过向您展示如何与 Xcode 13共享文档作结就由解释我为什么对新文档功能感到兴奋开始吧我相信我们都经历过我们都有想要使用的一些新框架或软件包当到了要将其整合为我们的程序代码的时候我们便需要弄清楚其中包含什么这就是需要Xcode 13介入的地方现在的Xcode为您的文档和程序代码提供编译器您可以构建并查看Xcode内所有Swift框架和软件包的文档我们称之为DocC 我们已将其全部整合于Xcode中以加强您读取和编写文档的方式现在 DocC不仅是事后运行的文档编译器它更是一个补充Xcode 完全整合的文档环境为你的文档提供一个丰富、实时的环境呈现在Quick Help中而丰富的程序代码完成功能可以将您的文档整合为一个完整的文档并可于整合的 “开发者文档”窗口中使用还有一个简单的选项是在Xcode和网络上分享预建文档这里仅举出几个例子请继续关注我们在 WWDC 2021上的其他DocC议程在这些议程上将更详细地讲解所有这些细节以及更多内容 DocC让你能够写出优秀的参考文档借助Xcode和Swift的力量在你的框架和软件包中为用户提供一个公开API的鸟瞰图并能够描述API如何共同工作而不只是孤立的但DocC不仅让您能够编写很好的参考文档我们很高兴能在今年展示额外两个使用DocC编写文档的方式文章让您为用户详细讲解您的框架背后的整个情况并给您机会将您框架中的个别项目与一个完整的故事连系在一起而教程是一个功能强大的逐步讲解解释如何运用您的框架去编写项目他们通过向您的用户提供一个对您框架彻底的指南介绍让您能比看参考文档或文章更深入了解

所有这些创作经验都影响并扩展 Markdown的能力和简易性使您创作文档时就如您编写程序代码般流畅如果您想了解更多使用原始码以外的文章和教程来组装一个文档目录您可以查看今年WWDC的这些议程

最后我们将在今年稍晚以开放原始码的状态发布DocC和一个web app 让您在网络上托管您构建的文档档案因此您可以利用这些新的文档作业流程甚至在Xcode以外也可以使用现在您已经体验了 Xcode 13中新文档的功能让我们深入讨论在Xcode中使用DocC构建您的文档让我们先快速看看它背后运作的原理若要构建您的文档 Xcode会构建您的框架和软件包并要求编译器储存有关其公开API的信息和您已编译的假影那些公开的API信息会交给DocC 然后将其与您的文档目录结合此目录包含于原始码以外编写的文章与教程以创建包含编译好的文档的最终存档要了解更多关于文档目录和组织您的文档请查看“提升您在Xcode中的 DocC文档”的议程幸好DocC与Xcode的构建系统进行整合对于您的目标所依赖的每个Swift框架和软件包此过程都会重复如此一来您就能将所有相关文档集中在一处但是这对您的日常文档需求有什么意义呢？要在Xcode 13中为Swift框架和软件包构建文档有三种方式

若按需求构建文档有个新的“构建文档”菜单项目能进行编译并上载您的文档如果你正在处理一个Swift框架并且总是想要随时预览您的文档那么每次编译时还会有一个新的构建设置来构建文档对于您的命令行和CI需求 xcodebuild也有一个新命令来构建文档这跟在Xcode中选择构建文档的构建运行相同但它是在命令行上使用xcodebuild 我的同事大卫会在 “托管和自动化 DocC文档”议程部分提供更多关于自动化文档作业流程的信息让我们看看它的实际效果我的队友已经研究这个名为 SlothCreator的软件包一段时间这个软件包是关于编目和定制可爱的小树懒我想尝试一下所以让我们看看它在Xcode 13是如何运作的我设置了这个app 我称之为Slothy 所以我可以使用SlothCreator 去定制我的树懒并在运行时预览它们我已经将 SlothCreator 设置为我的app的依赖项但有关它提供哪些API 我想了解更多于是我们打开“产品”菜单…

并选择“构建文档”看看

就像这样开发者文档窗口打开了然后在导航器中我可以延伸我的Slothy项目和我正在使用的 SlothCreator软件包以便在导航器中查看概述我将在主视图中加载SlothCreator概述如果我往下滚动则会看到可用的类型和协议列表

这里我可以看到这种称为Habitat的类型让我们点按它以加载它的页面

这里有一些很不错的信息但我想知道是否有其他任何信息已经提过了我们选择顶部的搜索栏并查找Habitat

似乎有其他的项目也提到它让我们点按这个“睡眠”方法以叫出它的文档页面

此页面特定于“睡眠”方法但我很好奇它属于哪种类型在窗口顶部的跳转栏中我看到这是Sloth类型的一部分

如果我点按这个Sloth 会出现一个下拉菜单如果我再次点按它我就可以打开该类型的文档页面现在我明白了所有这些 API是如何组合在一起所以我们现在有机会详细讲解SlothCreator的文档让我们回顾一下看看它是如何做到这一点我的同事伊森将首先展示Xcode 13中的一些新功能以编写出色的文档开始吧谢谢维多利亚现在我们已经了解Xcode 13 对构建和浏览文档的强大支持我想向您展示一些技巧以使用DocC编写更好的文档

DocC是围绕源内文档的优势而设计的您将文档与程序代码一起编写从而轻松方便地与现有开发作业流程整合在一起

要将文档添加到声明中您只需在其正上方写一种特殊的注释这可以轻松地使您的文档与您将来可能更改的任何程序代码保持同步当然它也会适合您现有的以文字为基础的工具例如 git diffs

您可能已经为您的原始码加了注释以便为日后您的代码库维护人员提供额外的上下文在Swift和许多其他语言中您使用两个正斜杠开始您的句子编写注释编写这些注释对帮助维护人员日后理解您的代码库并提高效率方面起到很大的作用但是如果您想帮助您框架的时下采用者呢？这就是文档注释的用途通过编写以三个正斜杠开头的注释您是在告诉 Swift文档编译程序将该注释与其下方的声明联系起来注释将被包含在符号的编译文档页面中任何导入您框架的人都可进入如果您较喜欢使用块状注释您可以通过在开头的分隔符中包含一个额外的星号来创建该样式的文档注释让我们看看这一切在现实中是如何运作的正如维多利亚提到过去几个月里我们一直在研究SlothCreator框架 SlothCreator是一个Swift软件包它提供了对可爱小树懒进行分类和定制的功能作为SlothCreator的开发者我想确保该框架的任何采用者都能轻松上手因此我一直努力在我处理的代码库部分添加文档注释我尤其想确保SlothCreator中的每个公开API有详细的记载因为任何导入我框架的人都可以查看这些API 同样地 DocC仅为您的框架中的公开和开放的符号生成文档页面 SlothCreator中只有几个符号仍需要记录让我们从这个“食物”结构开始我将首先在类型声明上方添加三个正斜杠

以创建文档注释然后我会写这是 “树懒可以吃的食物” 我的文档注释的第一行将变成符号的摘要但我想在讨论部分添加一些额外的信息我现在将添加一个在我的摘要之后添加一个换行符号然后为树懒喜欢的食物种类添加一些额外的细节并且因为DocC完全支持Markdown 我可以添加一个使用Markdown的围栏代码块语句的程序代码例子

好的我认为这为“食物”结构添加了一些非常有用的附加上下文让我们通过重建文档来看看我的文档现在的样子我可以通过将鼠标向上移动到“产品”菜单然后选择“构建文档”而做到

Xcode现在将与框架本身一起重建SlothCreator的文档因为我在这个构建中使用了“构建文档”按钮当它完成时 “文档查看器”将打开我更新的文档但我其实有兴趣直接转到 “食物”结构的页面来查看我们刚刚添加的注释幸运地 Xcode有一个名为Quick Help的功能可以让我做到这一点 Quick Help在源码编辑器中提供了符号文档的简短摘要版本

我现在可以通过按住 “选择”键然后点按 “食物的声明”来尝试一下但是SlothCreator的采用者可以通过选项点按其程序代码中有关“食物”结构的任何引用来打开相同的视图所以我们写的注释就在摘要和讨论部分但如果我要查找的不仅是摘要的视图那么Xcode 13中的新功能 “在开发者文档打开”链接可以做到

如果我将鼠标移到 Quick Help视图的右下角并点按“在开发者文档中打开” “文档”窗口将直接启动到该符号的页面非常好 SlothCreator中还有一个符号仍然缺少文档我把鼠标移到Xcode的导航器并点按Sloth项目来打开Sloth文档如果我往下滚动我会发现 “吃”的方法仍然需要文档注释让我们快速看一下记录方法的最佳方式

我们以同样的方式开始在方法的声明上方添加一个三斜线注释并添加构成其文档摘要的文本但是我们还应该具体记录我们预期作为参数传递的内容

我们可通过“参数”部分做到这一点通过编写一个以单词“参数” 开头的Markdown列表项接着是方法参数的名称、冒号然后是其文档您便可以在文档中添加一个“参数”部分您可以用非常相似的方式添加“回传”部分这一次通过编写“回传”分隔符后跟一个冒号和您的方法回传的描述但如果你的方法有多个参数怎么办？这种情况下最好的办法是从单数的“参数”分隔符变成复数的“参数”分隔符除了您的参数名称被写为父“参数”分隔符的子项之外这与其他作业操作非常相似所以现在我们已经了解基本原理让我们记录一下树懒“吃”的方法现在我可以用相同的方式通过手动编写以三个正斜杠开头的文档注释来开始记录“食物”结构但由于我要记录一个更复杂的符号我将利用Xcode 强大的“添加文档”功能该功能将插入一个最适合记录当前声明的样板

通过按住“命令”键然后点按该方法的声明以打开“操作”菜单来执行此操作接下来我可以点按 “操作”菜单中的 “添加文档” 就像这样我有很棒的样板能开始记录我的方法

我将首先填写方法的摘要然后我将描述食物和数量的参数以及该方法回传的内容然后我将通过添加讨论部分和程序代码例子来结束文档

就像上次一样我可以通过将鼠标移动到“产品”菜单并选择“构建文档”项来重建文档

再一次 Xcode与框架本身一起构建我的文档这一次我将通过窗口的导航器导航到Sloth结构我将在Sloths主题群组中找到Sloth 如果我在Sloth页面往下滚动就会在“实例方法” 部分找到我的方法…

以及我更新的文档我对此已经非常满意此方法的输入和输出非常明确这里还有一个有用的程序代码例子虽然我认为这几乎已经准备好了但还是遗漏了一些东西如果我只阅读这一页文档我会很难理解应该要考量其他相关符号的上下文作为SlothCreator的维护人员我很想建议我的读者接下来应该考虑学习一些其他符号 Xcode 13的新功能是能够链接到文档中的符号这是连接框架不同部分一种非常好的方式并引导读者获取相关信息您可以通过新的双反引号语句编写这些链接我们一起看一个例子

这是我们之前记录的方法 “睡眠” 但它并不是被孤立隔绝的在Sloth结构上其实还有另一个属性

有一个值代表树懒的当前能量水平我认为重要的是让我的读者理解调用睡眠的副作用之一是树懒能量水平的变化

因此我将引用“能量水平”属性添加到我的方法讨论部分

在Xcode 13之前执行此操作的自然方法是将属性名称以等宽程序代码字体写入并用反引号将其括起来但现在我可以转换为双反引号语句并创建一个链接现在链接到“能量水平”非常简单因为该属性是我正在记录的方法的同属兄弟就像在Swift中引用局部变量时一样我不需要进一步为我的链接从父级类型那里取得资格我可以只写属性的名称“能量水平” 但是如果我想引用不同类型的子级我就需要更具体一点所以在这里我写下 Habitat/comfortLevel 来链接到Habitat结构的子级好的让我们通过为“吃”的方法添加一些链接于文档中来看看这在现实中是如何运作的我将在这里开始写 “它们进食的时候树懒的…” 现在我要为“能量水平”属性写一个符号链接因此我将键入两个反引号然后我将开始编写“能量水平” Xcode的程序代码完成功能帮助我确保获得正确的链接我会继续选择那个项目

所以我会说能量水平 “随着食物的增加而增加” 现在我将引用 “食物”结构的一个子元素我将再次以两个反引号开始接着我会写“食物” 一个正斜杠然后是能量

我现在创建了两个符号链接我认为它们会真正帮助我的读者更加理解关于此方法的上下文这些链接甚至可以在Quick Help中查看所以我将按住“选择”键并点按我的方法声明以打开Quick Help的弹出提示框这是我们添加的讨论部分当然在讨论中还有我们的两个链接如果我点按一个我会直接进入 “文档”窗口中引用的符号页面现在我已经为SlothCreator中每个公开API编写了很好的文档注释我真的很高兴能与我的同事分享此功能甚至可能使它适用于网络上我可以通过Xcode输出的每个文档构建的一部分文档档案来做到文档档案包含一个单页网络app 可用于网络上共享文档我的同事大卫将在他的 “托管和自动化您的DocC文档” 议程中解释如何做到这一点我强烈推荐你看看那视频

但是Xcode也支持直接从“文档”窗口导出和导入您的文档现在让我们来看看我先将鼠标移到窗口的“导航器”上接着从“文档”窗口导出SlothCreator 当我将鼠标悬停在 SlothCreator框架项时会出现一个上下文菜单图标点按它然后选择“导出”

再将它储存到我的“桌面” 好的现在我准备将它发送给我的同事如果他们只需双击存档它就会在Xcode的 “文档”窗口中打开但由于我已经了解 SlothCreator 所以我想打开一个不同的文档档案我最近一直在与团队讨论将命令行界面添加到 SlothCreator会很棒我的一位同事提到 ArgumentParser是一个可以提供帮助、很棒的开源框架他们向我发送了ArgumentParser的最新文档档案我们现在打开它只需双击文档档案就像这样就可以立即开始学习文档是开发成功且持久的框架的关键您会发现直接在源代码中编写文档是非常方便和有效的 Xcode 13中的新功能与DocC的整合让您为编写出色文档的所有付出都会以全新且有效的方式获得回报

我们在WWDC上还有其他几个议程可以真正帮助您将文档提升到一个新的水平在 Xcode中“提升您的DocC文档” 会从这次议程结束的地方继续向您展示如何通过添加文档目录更好地组织您的文档我之前提到过 “托管和自动化您的DocC文档” 将会解释如何整合文档构建到您现有的持续整合设置以及如何在线托管您的文档

最后如果您的框架中有更复杂的部分能够从逐步讲解中获益我建议您查看“在DocC中构建互动式教程” 它将向您展示如何做到这一点

谢谢观看 [打击乐]

9:34 - Existing comments in code

// A model representing a sloth.
public struct Sloth {
    // ...
}

10:05 - Writing documentation comments

/// A model representing a sloth.
public struct Sloth {
    // ...
}

10:22 - Writing block-style documentation comments

/** 
 A model representing a sloth.
 */
public struct Sloth {
    // ...
}

11:34 - Documenting the Food struct

/// Food that a sloth can consume.
///
/// Sloths love to eat the leaves and twigs they find in the rainforest canopy as they
/// slowly move around. To feed them these items, you can use the `twig`,
/// `regularLeaf` and `largeLeaf` default foods.
///
/// ```swift
/// superSloth.eat(.twig)
/// ```
public struct Food {
		// ...
}

13:58 - Documenting the Sloth.sleep(in:for:) method

/// A model representing a sloth.
public struct Sloth {
    /// Sleep in the specified habitat for a number of hours.
    ///
    /// - Parameters:
    ///     - habitat: The location for the sloth to sleep.
    ///     - numberOfHours: The number of hours for the sloth to sleep.
    /// - Returns: The sloth’s energy level after sleeping.
    mutating public func sleep(in habitat: Habitat, for numberOfHours: Int = 12) -> Int {
        energyLevel += habitat.comfortLevel * numberOfHours
        return energyLevel
    }
}

15:39 - Documenting the Sloth.eat(_:quantity:) method

/// A model representing a sloth.
public struct Sloth {
    /// Eat the provided specialty sloth food.
    ///
    /// Sloths love to eat while they move very slowly through their rainforest habitats. They
    /// are especially happy to consume leaves and twigs, which they digest over long periods
    /// of time, mostly while they sleep.
    ///
    /// ```swift
    /// let flower = Sloth.Food(name: "Flower Bud", energy: 10)
    /// superSloth.eat(flower)
    /// ```
    ///
    /// - 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.
    mutating public func eat(_ food: Food, quantity: Int = 1) -> Int {
        energyLevel += food.energy * quantity
        return energyLevel
    }
}

17:46 - Adding symbol links to the documentation for Sloth.sleep(in:for:)

/// A model representing a sloth.
public struct Sloth {
    /// The energy level of the sloth.
    public var energyLevel: EnergyLevel

    /// Sleep in the specified habitat for a number of hours.
    ///
    /// Each time the sloth sleeps, their ``energyLevel`` increases every hour by the
    /// habitat's ``Habitat/comfortLevel``.  
    ///
    /// - Parameters:
    ///     - habitat: The location for the sloth to sleep.
    ///     - numberOfHours: The number of hours for the sloth to sleep.
    /// - Returns: The sloth’s energy level after sleeping.
    mutating public func sleep(in habitat: Habitat, for numberOfHours: Int = 12) -> Int {
        energyLevel += habitat.comfortLevel * numberOfHours
        return energyLevel
    }
}

18:44 - Adding symbol links to the documentation for Sloth.eat(_:quantity:)

/// A model representing a sloth.
public struct Sloth {
    /// Eat the provided specialty sloth food.
    ///
    /// Sloths love to eat while they move very slowly through their rainforest habitats. They
    /// are especially happy to consume leaves and twigs, which they digest over long periods
    /// of time, mostly while they sleep.
    ///
    /// ```swift
    /// let flower = Sloth.Food(name: "Flower Bud", energy: 10)
    /// superSloth.eat(flower)
    /// ```
    ///
    /// When they eat food, a sloth's ``energyLevel`` increases by the food's
    /// ``Food/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.
    mutating public func eat(_ food: Food, quantity: Int = 1) -> Int {
        energyLevel += food.energy * quantity
        return energyLevel
    }
}

正在查找特定内容？在上方输入一个主题，就能直接跳转到相应的精彩内容。