DoccGPT 🧹

DoccGPT 是一个尝试完全自动化 Swift 代码库文档化的实验。目前尚未完全实现，但我们会努力达成目标（请阅读下面的常见问题解答）。

它通过利用 OpenAI 和 Apple 的文档编译器 DocC 来工作。

DocC 文档编译器将基于 Markdown 的文本转换为 Swift 和 Objective-C 项目的丰富文档，并在 Xcode 文档窗口中直接显示。您还可以将此文档托管在网站上。

通过将 DoccGPT 与 Swift Package Index (它为您编译和托管文档) 结合使用，您可以非常接近完全自动化的自文档化代码库。 DoccGPT 为您编写标记，或至少进行初始处理，而 Swift Package Index 负责为您编译和托管生成的文档。

/Sources 中的几乎所有标记都是通过在自身上运行 DoccGPT 生成的。

+ /// A class for running the OpenAI GPT API to document Swift files.
struct DoccGPTRunner {

  // MARK: Internal

+ /// The API key used to authenticate with the OpenAI API.
  let apiKey: String

+  /**
+   Runs the OpenAI GPT API to document Swift files in a directory.
+
+   - Parameter directoryURL: The URL of the directory containing the Swift files to document.
+
+   - Throws: `DoccGPTRunnerError` if an error occurs.
+   */
  func run(in directoryURL: URL) async throws {
    try await documentFiles(in: directoryURL)
  }

  // MARK: Private

+ /// The base URL for the OpenAI API.
  private let baseURL = URL(string: "https://api.openai.com/v1/completions")!

+ /// The `FileManager` used to access the filesystem.
  private let fileManager = FileManager.default

+ /// A set of files to ignore when running the OpenAI API.
  private let ignoredFiles: Set<String> = [
    "Package.swift",
  ]

根据它使用的 OpenAI 模型，DoccGPT 足够智能，可以记录长而复杂的 Swift 代码。 较简单的模型似乎随着代码量的增加而更加吃力。

运行可执行文件，并提供一个目录以及您的 OpenAI 密钥。

警告 DoccGPT 将尝试重写您提供给它的目录中每个 .swift 文件的内容。 并且如果您向它提供足够长的文件，它将无法到达结尾！

swift run docc-gpt <directory> [--model <model>] --key <key> [--log-level <log-level>] [--skip-files <skip-files>]

ARGUMENTS:
  <directory>             The folder whose contents you want to document

OPTIONS:
  -m, --model <model>     The id of the OpenAI model to run (default: Model(id: "gpt-3.5-turbo", contextLength: 4096))
  -k, --key <key>         Your secret API key for OpenAI
  -l, --log-level <log-level>
                          The desired log level (default: info)
  --skip-files <skip-files>
                          Whether or not files that are too long to documented should be skipped (default: true)
  -h, --help              Show help information.

DoccGPT 是一个用 Swift 编写的命令行工具，它遍历给定目录中的所有 .swift 文件，并尝试使用 DocC 语法记录您的代码。

DocC 语法 - 称为文档标记 - 是 Markdown 的自定义变体，它为特定于开发人员文档的功能添加了功能，例如跨符号链接、术语定义列表、代码清单和旁注。

在撰写本文时，文档标记是通过将整个 .swift 文件馈送到 /v1/chat/completions 来生成的。 我没有注意到 gpt-3.5-turbo 和 gpt-4 之间的性能有任何可比的差异。 馈入整个文件听起来可能很幼稚，但它似乎导致了一些非常令人印象深刻的行为——我对 /Sources 中一些注释的具体程度以及模型在添加注释之前似乎“读取”整个文件的方式感到惊讶。

最大的问题是当前可用模型的上下文窗口。 我无法完全记录 DoccGPTRunner.swift，因为我用完了 token，即使使用 GPT-4 也是如此。 在撰写本文时，当前的 token 限制对于我认为的平均 Swift 文件来说是不可行的。 但是，即将推出的 GPT-4 的 32k token 上下文窗口应该会大大增加 DoccGPT 的范围，并使我们更接近生产就绪工具。

我还没有弄清楚如何对已经记录过的文件重新运行模型。 对于更复杂的代码，模型会做出与之前所做不同的决定。 对已经注释过的代码进行第二次传递似乎总是会导致糟糕的更改。 也许最重要的是，我还没有弄清楚如果功能发生了变化，如何让它重新记录代码。 也就是说，所有这些都可能通过更好的提示或更好的模型来解决。

最后，还需要相当多的其他基本 CLI 工作才能使所有这些都达到可用状态，例如公开忽略某些文件/子目录的能力。

我不知道将整个代码库发送到 OpenAI 服务器的隐私影响，但仅出于这个原因，我可能不会使用它。

假设我们解决了隐私影响和上述限制，也许？ 我可能会避免通过 CI 自动提交任何内容，尽管这些模型似乎非常擅长以确定性和高质量的方式首次记录代码。

也就是说，我认为在不久的将来期待完全自动化的自文档化代码库并非遥不可及。 我目前的第一印象是，好的提示很有帮助，并且不同型号/ API 之间存在巨大的性能差异。 我很高兴在未来我们可以在本地运行具有大上下文窗口的强大模型。

好奇的读者可能会注意到，提示中使用的一些文档示例来自无与伦比的 NSHipster。 我一直是 NSHipster 的长期粉丝，并且非常感谢 NSHipster 为世界各地的移动开发人员所做的一切。