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.

H4Hugo
  • 2,570
  • 3
  • 16
  • 32
  • @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 '16 at 09:11
  • It's demonstrated in some WWDC 2016 videos. – Rob Jun 28 '16 at 09:17
  • 1
    https://developer.apple.com/videos/play/wwdc2016/102/ – Rob Jun 28 '16 at 09:26
  • 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. – Confused Vorlon Jun 29 '16 at 14:56

2 Answers2

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.

Rob
  • 415,655
  • 72
  • 787
  • 1,044
  • 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... – Confused Vorlon Jun 29 '16 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 '16 at 22:10
  • 2
    I just tried a reboot, but still no joy. I have submitted a bug report. – Confused Vorlon Jun 30 '16 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. – Chris Hanson Jul 15 '16 at 07:47
  • Why was `///` chosen for the auto generated multi-line comments instead of `/**` and is there a way to change that in preferences somewhere? – Adam Johns Aug 30 '16 at 03:16
  • Why? Only Apple knows. (Personally, I prefer this format, so I'm not going to complain.) Can you have it change the convention for the automatically generated comments? Not that I know of. Post an enhancement request at http://bugreport.apple.com if this bothers you. Or I know that Xcode has richer integration for third party utilities, so you might be able to write your own, if you want. See [Using and Extending the Xcode Source Editor](https://developer.apple.com/videos/play/wwdc2016/414/). – Rob Aug 30 '16 at 03:22
  • In Xcode 8 GM, the command to generate the source documentation with style `/** @returns A value. */` also works for Objective-C - except, that no Quick Help is generated :( – CouchDeveloper Sep 13 '16 at 07:23
  • @CouchDeveloper - "except that no Quick Help is generated" ... huh? If I press `⌥`-`⌘`-`/` when on Objective-C method, it auto generates the documentation with `/** ... */` format, and if I save that file, Quick Help for that method works fine. I don't understand your point. – Rob Sep 13 '16 at 15:24
  • @Rob Well, at least on my machine it doesn't generate the Quick Help. It's Xcode Version 8.0 beta 6 (8S201h) and Xcode 8 GM. Possibly, it takes quite a bit of time until the docs are generated. Indexing takes about a minute. So, I checked again after a while, and the Quick Help will actually be generated and is available after a few minutes. – CouchDeveloper Sep 14 '16 at 06:35
  • Hmm. It's working on my two machines with Xcode 8.0 (8A218a), a slow, old, iMac running El Capitan and a newer MBP running Sierra. The only trick that I've noticed is that the quick help doesn't show up until the .m file is saved. Also the Xcode beta release notes reportedly used to have some caveat about doing this on El Capitan, but (a) I don't see that in the GM release notes anymore; and (b) I personally never had to do that anyway. Sorry it's not working for you. :( – Rob Sep 14 '16 at 07:06
  • 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. – Lloyd Sargent Oct 05 '16 at 16:08
  • Regarding the sporadic nature, while I don't deny that there might be some issues, I will warn future readers that auto-generation may not work if there are any compilation errors in your code, that can prevent it from successfully parsing the method and thereby interfere with auto generation. And what it generates is generally not just the method name and description placeholder, but also placeholders for any parameters and return type. – Rob Jan 20 '17 at 16:26
  • I don't understand because in swift I get the `///` format whereas in c++ file I've `/**/` format. Is there any chance someone knows where we could edit this snippet? – DEADBEEF May 12 '17 at 15:12
  • Might be a bit off-topic, but is it possible to generate documentation files in Xcode / using these comments? – Thizzer Jul 18 '17 at 07:52
  • 1
    @Thys For documentation in Xcode, the above is all you need. For external documentation, while I haven’t used it recently, you should check out [jazzy](https://github.com/realm/jazzy). – Rob Jul 18 '17 at 08:05
  • Does this work on Xcode 9? If I press cmd + option + / the text in the editor just gets smaller :) If I type /// nothing happens. I am using Xcode 9.4.1. and os X 10.13.5 – SimpleApp Jul 05 '18 at 08:36
  • It's a bit particular about where the cursor has to be. I used to be just about anywhere in the function and press command+option+/, but it doesn't always work. But I find that if the cursor is located in the name of the function itself, it seems to work consistently for me in Xcode 9.4.1 and macOS 10.13.5. – Rob Jul 05 '18 at 13:57
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.

Klaus Busse
  • 159
  • 1
  • 3
  • There was this bug in Xcode 8 beta but it's been fixed in the released version. – Eric Aya Sep 16 '16 at 11:19
  • 8A218a is the released version - and the comment shortcut works again for me (didn't in betas). – Eric Aya Sep 16 '16 at 11:30
  • Are you on a keyboard layout, where you get '/' without using shift? – Klaus Busse Sep 16 '16 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 '16 at 11:41
  • Well, it is intermittent for me (American keyboard). – Lloyd Sargent Oct 05 '16 at 16:24
  • @KlausBusse isn't working on my German layout keyboard, too. Did you get it to work since then? – regetskcob Oct 13 '16 at 19:17
  • For me the issue was that other shortcuts were overriding the documentation shortcut. E.g. ⌥ + ⇧ + 7 produces a backslash "\" on a German keyboard, so if you press ⌘ + ⌥ + ⇧ + 7 it's effectively like pressing ⌘ + \ which is the default shortcut for adding a breakpoint in my Xcode installation. So just make sure that you remove all shortcuts that might be conflicting with the documentation shortcut and it will work as expected. – Mischa Nov 15 '16 at 16:54
  • It's still just a workaround for something Apple should have thought about in the first place but for those who are really used to that particular key combination for adding documentation it at least does the job. ;) – Mischa Nov 15 '16 at 16:58
  • For me it seems to work, but only for protocol signature... Everywhere else I get /// Description – Flupp Jul 17 '18 at 11:49