I don't see this documented, but it appears that you need to use three slashes /// for comments if you want them to be parsed and viewable in Xcode when you Option-click a symbol. Is this type of comment (and the markdown-ish whatever language that you can use in such comments) defined as part of the Swift language or is it something extra that Xcode is doing? I don't see in the Swift language docs. Is there a way to tell Xcode to parse // comments the same way. I don't like the look of "///" and apparently I have an obsession with this kind of thing that isn't shared by most developers...
Yes, the allowed documentation comment forms are defined by the Swift compiler (and other tools built from it that manipulate code documentation, like SourceKit), so it only supports line-based (
///) or block-based (
/** ... */) documentation comments. Regular line comments (
//) or block comments (
/* ... */) aren't parsed as documentation.
One quick way to verify this is by producing a hex dump of the
.swiftdoc file that gets generated when you compile a module; you'll find the contents of your
/** ... */ comments, but not the others.
NSHipster has a great post describing the documentation markup capabilities of Swift. I refer to it frequently when documenting my code.