Three slash comments - language or Xcode?

Hi,

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... :slight_smile:

Rob

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 /// and /** ... */ comments, but not the others.

2 Likes

NSHipster has a great post describing the documentation markup capabilities of Swift. I refer to it frequently when documenting my code.

6 Likes