Xcode 8 自动生成的快速帮助文档 [英] Xcode 8 auto-generated quick help documentation

问题描述

在

像我们可以从 NSHipster 的这篇文章中学到的那样，手动代码文档就这样结束了吗?

有人可以概述这个新功能的优缺点吗?它是否会取代 Jazzy 之类的工具?

我找不到有关新功能的更多信息.

解决方案

这是指 Xcode 8(及更高版本)功能，您可以在其中选择这样的方法:

func foo(bar: Int) ->细绳 { ... }

... 然后按 ⌘+option+/(或从 Xcode 的编辑器"中选择结构"»添加文档""菜单)，它将为您生成以下评论模板:

///<#Description#>//////- 参数栏:<#bar description#>//////- 返回:<#return value description#>

它只是方便了快速帮助文档的编写.

---

请注意，虽然这种行为随着时间的推移而发生了一些变化，但当您尝试执行此操作时，Xcode 可能会特别注意光标所在的位置.例如，光标必须位于函数名称中的某个位置，在我上面的示例中为 foo，这样才能工作.或者只需双击函数名称，然后按 ⌘+option+/

---

您询问此功能是否会取代 Jazzy 等工具.

不，它不会取代 Jazzy 或类似工具.除其他外，Jazzy 从这个内嵌文档创建了独立的 HTML 文档.因此，这只是您是否出于任何原因需要这些来自 Jazzy 的独立输出的问题.如果是这样，请将 Jazzy(或类似工具)与此集成文档结合使用.如果不是(即，您只是在 Xcode IDE 中查找文档)，则不需要 Jazzy.

Among the new features announced in Xcode 8, we can see

"Auto-generate Quick Help documentation" :

Is this the end of manual code documentation like we can learn on this article from NSHipster ?

Can someone outline the pros and cons of this new feature ? Does it replace tools like Jazzy ?

I couldn't find more information about the new feature.

解决方案

This refers to Xcode 8 (and later) feature, where you can select a method like this:

func foo(bar: Int) -> String { ... }

... and then press ⌘+option+/ (or choose "Structure" » "Add documentation" from Xcode's "Editor" menu) and it will generate the following comments template for you:

/// <#Description#>
///
/// - parameter bar: <#bar description#>
///
/// - returns: <#return value description#>

It just facilitates the writing of documentation for Quick Help.

---

Note, while this behavior has changed a bit over time, Xcode can be particular about where the cursor must be when you attempt to do this. For example, the cursor has to be somewhere in the function name, foo in my above example, for this to work. Or just double click on the function name and then press ⌘+option+/

---

You asked whether this feature replaces tools like Jazzy.

No, it doesn’t replace Jazzy or similar tools. Amongst other things, Jazzy creates stand-alone HTML documentation from this inline documentation. So, it is simply a question of whether you need these stand-alone outputs from Jazzy for any reason. If so, use Jazzy (or similar tool) in conjunction with this integrated documentation. If not (i.e., you are only looking for documentation from within the Xcode IDE), then Jazzy is not needed.

这篇关于Xcode 8 自动生成的快速帮助文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！