How to use Swift documentation comments

This answer was last revised for Swift 5.2 and Xcode 11.4.

You can use markup to write standard code documentation (using /// or /** */) and rich playground documentation (using //: or /*: */).

/// This function returns a welcoming string for a given `subject`.
///
/// ```
/// print(hello("World")) // Hello, World!
/// ```
///
/// - Warning: The returned string is not localized.
/// - Parameter subject: The subject to be welcomed.
/// - Returns: A hello string to the `subject`.
func hello(_ subject: String) -> String {
    return "Hello, \(subject)!"
}

As for documenting related symbols, there is a SeeAlso markup tag but requires you to write an explicit URL to your related symbol's documentation page.

If you want to generate HTML documentation index for your project, I recommend checking out jazzy and swift-doc. They're both amazing open-source projects, and are even used by Apple itself.

Xcode 7.0 beta 4

The notation has been changed (:param: does not work anymore ...)

/// Creates the string representation of the poo with requested size.
///
/// - warning: Be carefull! Poos can hurt.
/// - parameter size: requested size of the poo
/// - returns: string representation of the poo
func makePoo(size: String) -> String
{
    return "Ouch. This is \(size) poo!"
}

And it looks like this:

You can use either /// or /** */

For those who want to add this as code snippet. Swift 5, XCode 11.3+

This is an add on to : Yogendra Singh's Answer in this thread

/**
<#Summay text for documentation#>

- parameter <#parameterName#>: <#Description#>.
- returns: <#Return values#>
- warning: <#Warning if any#>


 # Notes: #
 1. <#Notes if any#>

 # Example #
```
 // <#Example code if any#>
```

*/

Copy and paste the above code in Xcode. Select the code and then Right click.

Save the code snippet and give the completion name as documentation.

Now if we start typing documentation, the snippet will be shown in the code completion.

Use the following notation for documentation comments.

/**
 This method sum two double numbers and returns.

 Here is the discussion. This methods adds two double and return the optional Double.


 - parameter number1: First Double Number.
 - parameter number2: Second Double Number.
 - returns: The sum of two double numbers.

 # Notes: #
 1. Parameters must be **double** type
 2. Handle return type because it is optional.

 # Example #
```
 if let sum = self.add(number1: 23, number2: 34) {
  print(sum)
 }
 ```
*/


func add(number1: Double, number2: Double) -> Double? {
    return number1 + number2
}

(3) To generate your documentation in HTML (or even generate docsets), I strongly recommend jazzy which was built for that purpose.

Even if it's still WIP, it works really well and generate documentation with similar presentation to the Apple documentation