I'm trying to figure out how to do proper function commenting, and can't make it work. I'm using the below currently, but it's not working. My params are not called out as parameters, and the return isn't called out either. It's just all lobbed into the description.
/**
* Creates the UI element representing the match.
*
* :param: match The Match represented by this visual object.
* :param: showLoserLocation Whether or not to show the location to which the user is sent.
* :param: onClicked The function to be called when someone taps on this button.
*
* :returns: The UI element.
*/
static func createForMatch(match: Match, showLoserLocation: Bool = false, onClicked: (MatchButton) -> Void) -> MatchButton {I've also tried it without the leading astericks but that makes no difference.
Here is an interesting break down (ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7/). You can also look at the header files supplied by Apple to evaluate their syntax directly (Cmd-Click on an Apple Class). The only manual that matters is understanding how comments are managed in the API and then applying the same characteristics in your code. If you open the file utility and click quick help you will be able to see how Xcode displays the comments. When you do so you will find some well defined examples showing Apple's latest comment methods (yes, it does change over time so there is no substitute for looking at live examples). Please let me know if this answers your question by clicking the link below or if not, please refine your question if you need more assistance.
Sample implementation derived from the break down above:
/// - myfunction: This function does something important
/// - Parameter count: number of items
/// - Parameter name: collective description
/// - Returns: VoidApple API samples:
eg 1
/!
* @property interstitialPresentationPolicy
*
* @discussion
* The presentation policy determines whether the timing of presentation is entirely
* managed by the framework or should only take place when the application calls
* -requestInterstitialAdPresentation. By default the policy is "None", so to be
* able to present an interstitial it must be changed to either "Automatic" or "Manual".
*/eg 2
/!
* @method prepareInterstitials
*
* @discussion
* Ads involve network requests, so if an application needs to use interstitial
* ads and wants to ensure early availability, this method can be called to trigger
* a prefetch. If this method is not called, the first fetch will occur when a
* view controller's interstitialPresentationPolicy is set to something other
* than ADInterstitialPresentationPolicyNone.
*/For Playground files you can search the help documentation on "Adding and Viewing Rich Comments" I've noticed that the Objc Header files show excellent comments while the swift header files appear to be less complete (Xcode probably reads the objc headers first and then any properly formatted Swift headers).