Xcode 8 auto-generated quick help documentation

XcodeSwiftXcode8

Xcode Problem Overview


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

"Auto-generate Quick Help documentation" :

enter image description here

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.

Xcode Solutions


Solution 1 - Xcode

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 - Xcode

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.

Attributions

All content for this solution is sourced from the original question on Stackoverflow.

The content on this page is licensed under the Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.

Content TypeOriginal AuthorOriginal Content on Stackoverflow
QuestionH4HugoView Question on Stackoverflow
Solution 1 - XcodeRobView Answer on Stackoverflow
Solution 2 - XcodeKlaus BusseView Answer on Stackoverflow