Swift documentation
In the release notes for XCode 6 beta 5, they mention that they are using reStructuredText (quick reference) for javadoc style documentation.
It has a long way to go, but it’s a start.
Like Java, you can create documentation blocks like this:
|
1 2 3 |
/** whatever */ |
N.B. For old timey Objective-C guys, HeaderDoc uses /*! instead of /**
Or you can use three virgules (///) at the beginning of a line for single liners. Open Quick Help Inspector to see the comments, or option click on a variable/func of the type you’re documenting.
The notes state
Currently only block-level markup is supported (nested bullet and enumerated lists, field lists) [are supported].
Let’s see some field lists
|
1 2 3 4 5 6 7 8 |
/** This is a utility class to help clean the litterbox. :Author: Gene De Lisa :Version: 1.0 of 2014/08/05 :Dedication: To my cat, Giacomo. */ class LitterBox { ... |
How about bullet lists? Yes they work.
|
1 2 3 4 5 6 7 8 9 |
/** The metadata retrieved from the ipod library. - albumTitle - songs - artwork */ struct AlbumInfo { ... |
Enumerated lists? Not so much, even though they say they do. And other formatting like *bold* and **bolder** doesn’t work (they didn’t say it would yet).
You can use field lists for param and returns like this:
|
1 2 3 4 5 6 7 8 9 |
/** Queries the library for an artist name containing the parameter :param: artist The artist name :returns: Nothing. The delegate is notified. */ func albums(artist:String) { ... |
Formatting code in your comments? I don’t see anything yet. Also, in build settings, you can ask to be warned about Documentation Comments that are invalid. That doesn’t work for these comments yet.
