Xcode 8自动生成的快速帮助文档

在 Xcode 8发布的新功能中，我们可以看到

“自动生成快速帮助文档”:

enter image description here

这是手动代码文档的结束，像我们 可以从 NSHIpster 了解本文？

有人能概述一下这个新特性的优点和缺点吗？

我找不到关于新特性的更多信息。

40953 次浏览
小开
最佳答案

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.

小开

This is most likely related to the fact that ALL hotkeys with a '/' don't work in the current XCode 8 build, if your keyboard requires to press shift to get it.

I.e. on the german keyboard the '/' is shift+7, pressing alt+cmd+shift-7 doesn't do a thing. If you assign i.e. cmd+shift+opt+d, it works just fine.

The shortcut '///', which unfortunately also doesn't work right now, is probably due to the old XCode plugin VVDocumenter, which used exactly this shortcut.

Great feature, lousy QA on the Apple side.


提交答案