VVDocumenter-Xcode github README.md 中英文翻译

admin管理员组

文章数量:1567915

2023-01-22 19:29PM

Xcode 从版本 8 开始，直接使用快捷键即可生成注释文档。快捷键：option+command+/

---

最近在学习 Xcode 的使用，查到有一款用于生成注释文档的插件：VVDocumenter-Xcode
进入其 github 页面之后看 README，看到两句话：

1. Goodbye World： 再不更新了？
2. 从 Xcode 8 之后Apple官方提供了插件做相同的工作，是基于本项目的。

觉得这个项目很有意思，在此翻译一下其中的 README。

VVDocumenter-Xcode

---

Goodbye World

永别了

In Xcode 8, Apple integrated a comment documentation generator plugin, which is built on top of VVDocumenter. Now this project is proud to be a part of Apple. It means you could just use the shortcut (⌥ Option + ⌘ Command + /) to add a documentation comment to your code if you are using Xcode 8 or above!
从 Xcode 8 开始，Apple公司在本项目(VVDocumenter)的基础上，自己集成了一款用于生成注释文档的插件。
如今本项目对于成为 Apple 生态的一部分而深感荣幸。
这意味着：如果你在使用 Xcode 8 或其更高版本，直接使用快捷键(option+command+/)就可以在代码中生成文档注释。

VVDocumenter is one of my hobby projects from 2013, back to the age of Xcode 4. It serves well for these years and I am so glad that it helps a lot of developers to improve their productivity. Since there is no need to install this plugin anymore, the development of VVDocumenter will not continue. Yes, it’s time to say goodbye, with a happy ending.
回溯至 Xcode 4的那个年代，本项目始于2013年、是我的爱好项目之一。
这些年里它提供了很好的服务，我也很高兴它帮助了很多的开发者提高(了他们的)生产力。
因为以后(开发者/我们)不再需要手动安装这个插件了，所以本项目的开发将会终止。
是的，到了该说再见的时候了，已经有了一个圆满的结局。

Thank you all for your selfless support to this project. Let’s build more great things and make the world better in future!
非常感谢各位自发为本项目提供的支持。将来我们会一起制造更多更好的东西，让这个世界变得更美好！

What is this?

这是什么

Writing documentation is so important for developing, but it is really painful with Xcode. Think about how much time you are wasting in pressing ‘*’ or ‘/’, and typing the parameters again and again. Now, you can find the method (or any code) you want to document to, and type in ///, the document will be generated for you and all params and return will be extracted into a Javadoc style, which is compatible with appledoc, Doxygen and HeaderDoc. You can just fill the inline placeholder tokens to finish your document.
写文档在开发过程中很重要，可是在 Xcode 中这件事变得令人头疼。
回想一下你在敲击*和/、以及一次又一次拼写参数名的过程中浪费过多少的时间。
就那现在来说，你可以随意找一个需要你为其书写文档的方法（或一段代码），然后输入///，（紧接着）文档就会为你生成好，并且（该方法的）所有形参和返回值都会被提取、按照 Javadoc 的方式表现出来（Javadoc 是和 appledoc、Doxygen、HeaderDoc等标准兼容的）。
接下来你只需要手动填充（方法，参数，返回值等的）具体信息来替换占位符，文档就完成了。

Here is an image which can show what it exactly does.
这里有一张gif可以展示你操作的效果：

By the way, it also supports Swift now. Cheers!
哦对了，现在（该功能）也支持 Swift 语法了。干杯！

How to install and use?

如何安装以及使用？

The best way of installing is by Alcatraz. Install Alcatraz followed by the instruction, restart your Xcode and press ⇧⌘9. You can find VVDocumenter-Xcode in the list and click the icon on left to install.
最好的安装方式是通过 Alcatraz 站点。按照该站点中的指导去安装 Alcatraz ，重启你的 Xcode 后按下 ⇧⌘9 。
你可以在弹出界面中的列表中找到 VVDocumenter-Xcode 这一项，点击左侧对应的图标就会开始安装了。

If you do not like the Alcatraz way, you can also clone the repo. Then build the VVDocumenter-Xcode target in the Xcode project and the plug-in will automatically be installed in ~/Library/Application Support/Developer/Shared/Xcode/Plug-ins. Relaunch Xcode and type in /// above any code you want to write a document to.
如果你不喜欢 Alcatraz 的安装方式，你也可以直接克隆本项目的代码库到本地。
然后用 Xcode 打开该项目，编译 VVDocumenter-Xcode target，这样该插件就会自动安装到 ~/Library/Application Support/Developer/Shared/Xcode/Plug-ins 。
重新运行 Xcode 后，在任意你想为之写文档的代码的上一行输入 /// 就可以开始工作了。

If you want to use other text beside of /// to trigger the document insertion, you can find a setting panel by clicking VVDocument in the Window menu of Xcode. You can also find some other useful options there, including setting using spaces instead of tab in the panel or changing the format of generated documentation.
如果你不想用 /// 来触发文档插入，而是想用别的文本段，也有办法。
你可以点击 Xcode 窗口菜单栏中的 VVDocument 菜单项，在弹出的设置面板中有很多有用的选项，包括：“自动用多个空格替换跳格键”，“改变要生成文档的格式”。

Xcode version?

Xcode 版本？

This plug-in is supported in Xcode 5, 6 and 7. From Xcode 5, Apple added a UUID-verification to all plugins to ensure the stability when Xcode gets updated. The value of DVTPlugInCompatibilityUUIDs in project plist should contains current UUID of Xcode version, or the plugin does not work. And from Xcode 6.3, you will be prompt to “Load third party bundle” if you are using a plugin. You should always select “Load bundles” to enable this plugin.
这个插件可以在 Xcode 5， 6， 7 上使用。从 Xcode 5 开始，苹果公司新增了一种机制：当 Xcode 更新时会向每个插件都添加一个用于校验的 UUID 以确保稳定性。项目的 plist 配置文件中的 DVTPlugInCompatibilityUUIDs 变量的值应该包含：当前的 UUID 值，和 Xcode 版本，否则插件不能正常运行。
从 Xcode 6.3 开始，如果你使用一个插件，会有弹框提示你“是否要加载第三方的程序包”，你可以一直选择“加载该程序包”来启用该插件。

All plugins will be disabled once you update your Xcode, since the supported UUIDs in the plugins do not contain the one. You should try to clean your plugins folder (~/Library/Application Support/Developer/Shared/Xcode/Plug-ins by default) and clone/build the latest version from master branch. If you happened to skip the bundle loading, you can use this to reset the prompt:
当你更新 Xcode 之后，之前在里面装过的所有插件都会被禁用，因为在本版本 Xcode 可用插件对应的 UUID 的列表中不包含旧版本插件的UUID。
你要做的是去手动清空你的 Xcode 插件目录： (默认是 ~/Library/Application Support/Developer/Shared/Xcode/Plug-ins)，
然后克隆代码库，编译最新的 master 分支， 如果在之后的操作中你没有碰到关于程序包载入的弹框提示，可以用下面的命令去重设该弹框提示：

defaults delete com.apple.dt.Xcode DVTPlugInManagerNonApplePlugIns-Xcode-{your_xcode_version}

Please do not open an issue if this plugin not work in your newly updated Xcode. Pull request for new DVTPlugInCompatibilityUUIDs is welcome, and if UUID of your Xcode version is already there, please try to reinstall the plugin from a clean state.
如果本插件在你最新版本的 Xcode 中无法正常运行，请不要新开 issue
关于 DVTPlugInCompatibilityUUIDs 变量值的 PR 随时欢迎你提。
不过如果你的 Xcode 版本对应的 UUID 值已经合到了主分支，清尝试在 clean 状态下重新安装插件。

The default deployment target is 10.8. If you want to use it in a earlier OS version, you should change OS X Deployment Target (in project info setting) to your system version.
默认的部署目标(macOS版本)是 10.8 。
如果你想使用更早的操作系统版本，需要修改 OS X 部署目标到你自己的系统版本值（在项目信息设置的那个界面）。

Swift Support

Swift 支持

Yes, this plugin supports documentation for Swift 2 now. Check this post to see how to write the documentation for swift. By using VVDocumenter-Xcode, you can just type /// to make the magic happen.
是的，本插件现在也支持 Swift 2 了。看看这个网页中关于“如何向 Swift 代码添加文档注释”的内容。
通过使用 VVDocumenter-Xcode ，你只需要键入 /// 就能让魔幻之事发生。

The documentation format changed from Swift 1.x to 2. If you are using Swift 1.x, you could build from branch Xcode6 to get the support for the earlier format.
Swift 从 1 升版本到 2 时，文档的格式也有改动。
如果你在使用 Swift 1 ，可以从 Xcode6 分之编译来获取更早的格式。

Limitations and Future

当前局限性 & 未来发展

The plugin is using simulation of keyboard event to insert the doc comments for you. So it is depending the keyboard shortcut of Xcode. These two kinds of operation are being used:
本插件是通过模拟键盘事件的方式帮你自动插入大段文档的，所以它对 Xcode 的键盘快捷键是有依赖的。
这两种操作被应用：

• Delete to Beginning of the Line (⌘⌫) 删除到本行的行首（command ⌫）
• Paste (⌘V) 粘贴（command+V）

If you have modified these two shortcuts in your Xcode, the newset version of the plugin would not work correctly. Instead, you can use a earlier version such as this one(commit 03c4169ff7). Be causion you may suffer an undo and redo issue .
如果你在 Xcode 中修改了这两个快捷键，本插件的最新版本就不能正常运行了。
也有替代的解决方式：你可以使用更早的版本，比如：this one(commit 03c4169ff7)。
但是要小心点你可能会碰到这个问题：undo and redo issue 。

VVDocumenter-Xcode is now using regular expression to extract things needed, which is not the best way to do such thing. A better approach could be using the AST, and I also have a plan to do it later if I have some more time 😃
VVDocumenter-Xcode 现在已经开始用正则表达式来提取所需信息了（其实正则表达式并不是解决这个问题最好的方式）。
有种更好的解决方案就是用抽象语法树 (AST, Abstract Syntax Tree) ，我也有相关的计划就是如果之后我有更多的空余时间，我会用新方式去解决。

License

许可证

VVDocumenter is published under MIT License. See the LICENSE file for more.
VVDocumenter 是按 MIT 许可发布的，你可以查看该许可证内容获知更多明细。

本文标签： 中英文xcodeVVDocumenterGitHubmd