Apple DocC常见使用问题：排除符号、扩展文档生成及UIKit链接

DocC使用问题解决方案 #

1. 隐藏指定公共符号的生成文档 #

DocC提供两种实现方式：

• 通用官方方案：在需要隐藏的符号前添加@_documentation(visibility: private)修饰符，即可让DocC跳过该符号的文档生成，适用于所有Xcode 13及以上版本
• 兼容写法：Xcode 14及以上版本已支持/// :nodoc:标记，和你此前在Jazz中的使用方式完全一致，直接加在对应方法上方即可生效

2. 系统类扩展文档不展示问题 #

这是DocC的默认行为，不是Bug，默认不会将对外部框架的扩展纳入你的模块文档。开启方法如下：

• 如果你使用Xcode项目：在目标的构建设置中搜索DOCUMENTATION_EXPORT_EXTENSIONS_TO_MODULE，将值设置为YES
• 如果你使用Swift Package：在Package.swift中为DocC插件添加--include-extended-types运行参数，重新编译生成文档即可看到扩展内容

3. 引用扩展方法的链接写法 #

你遇到的无法生效问题，确实和扩展文档未生成有关，先完成上述第二步的配置，确保扩展已纳入文档生成范围后，原有的写法基础上补充你的模块名前缀即可生效，示例如下：

/**
 An enum for use when using `你的模块名/UIView/applyElevation(_:)`
 */

加模块名是为了避免和其他框架的同命名扩展产生歧义，保证链接正确指向你自己实现的扩展方法。

4. 链接苹果官方框架符号的写法 #

DocC默认不会自动识别未加前缀的外部框架符号，正确写法是在符号前补充对应官方框架的名称，用双反引号包裹即可，示例如下：

• 链接UIView类：UIKit/UIView
• 链接UIView的layoutSubviews方法：UIKit/UIView/layoutSubviews()
  如果配置后仍无法跳转，检查构建设置中DOCUMENTATION_LINK_TO_DEVELOPER_DOCUMENTATION是否为开启状态，该选项默认值为YES，关闭后会禁止跳转至苹果官方文档。

内容的提问来源于stack exchange，提问作者Ricardo