Xcode 8 auto-generated quick help documentation

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.

Solution 1:

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.

Solution 2:

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.