87

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.

4
  • @Rob: Any idea how I could sea how it looks like without having the pain of installing Xcode 8 bêta and uninstall it right after (not authorized to install it on my job's mac)
    – H4Hugo
    Jun 28, 2016 at 9:11
  • It's demonstrated in some WWDC 2016 videos.
    – Rob
    Jun 28, 2016 at 9:17
  • 1
  • 2
    You can see a demo in the video at 37:00 - however I can't get it to actually work! I have tried with swift and obj-c and with various different parts of a function selected. Jun 29, 2016 at 14:56

2 Answers 2

208

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.

17
  • 1
    can you get it to work? I can't. If you can; what are you selecting when you use the command? I have tried just about every option... Jun 29, 2016 at 14:57
  • 2
    I just put my cursor somewhere in the method name and then press command+option+"/" (as well as having chosen "Editor" - "Structure" - "Add documentation") in Xcode 8 and it works fine. The only problem I've encountered so far is that it seems to be confused with @IBAction methods. But it works with both Objective-C and Swift fine. If you're still having problems and have tried the usual lame procedure of restarting Xcode and/or rebooting your machine, you might just want to post a bug report on this beta software.
    – Rob
    Jun 29, 2016 at 22:10
  • 2
    I just tried a reboot, but still no joy. I have submitted a bug report. Jun 30, 2016 at 12:11
  • 5
    It actually is working as of Xcode 8 beta 1, but if you’re using El Capitan you need to do launch Xcode, let it install required system components, and then run sudo /usr/libexec/xpccachectl in Terminal and restart your Mac before it or any other Xcode Extensions will work. See the Xcode 8 release notes. Jul 15, 2016 at 7:47
  • 1
    I find that it works sporadically. Sometimes it works great and other times not at all. Nor have I discovered why. Frankly, when it does work, I find the things that it auto-generates to be rather sparse (method name in the Description?). For those of you that it works with no problem, awesome. For some of us, it is sporadic or just doesn’t work. Oct 5, 2016 at 16:08
7

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.

9
  • There was this bug in Xcode 8 beta but it's been fixed in the released version.
    – Eric Aya
    Sep 16, 2016 at 11:19
  • 8A218a is the released version - and the comment shortcut works again for me (didn't in betas).
    – Eric Aya
    Sep 16, 2016 at 11:30
  • Are you on a keyboard layout, where you get '/' without using shift? Sep 16, 2016 at 11:40
  • Yes, I have two keyboards, a French Azerty one with "/" on top of ":" and an american Qwerty one. Both work ok for the comment shortcut.
    – Eric Aya
    Sep 16, 2016 at 11:41
  • Well, it is intermittent for me (American keyboard). Oct 5, 2016 at 16:24

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.