How to use Swift documentation comments

Question

I have a few questions about Swift documentation comments:

1. Is there a way to make a Related declarations section like some of the Apple documentation has? For example, when I Option+Click the tablewView(_:heightForRowAtIndexPath:) method, it links me to three other related methods within the generated documentation.

2. Is there any warning tag in Swift? I know Objective-C allowed me to do @warning and get a bolded warning in the generated documentation. However, :warning: does nothing in Swift's documentation comments, so I was curious if there was another way.

3. Is there a way to make my documentation into an HTML file that is a similar format as the Apple Documentation? I know in other IDEs, such as Eclipse, I can generate HTML documentation for my code. Does XCode have this?

Solution 1

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.

Solution 2

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 /** */

Solution 3

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.

Solution 4

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
}

Solution 5

(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

View more solutions

Comments

[Saranjith]

This answer must come up

[adev]

@akashivskyy If this is added in a dynamic swift framework, it is removed in the public interface. So the projects using the framework cannot view these documentation. Any idea how to fix that?

[adev]

If this is added in a dynamic swift framework, it is removed in the public interface. So the projects using the framework cannot view these documentation. Any idea how to fix that?

[akashivskyy]

@adev I cannot reproduce what you wrote. I added a precompiled .framework to my project, cmd-clicked a symbol and all the original doc comments are available.

[adev]

@akashivskyy That is strange. I wonder if carthage is stripping something when it adds my framework to application.

[akashivskyy]

@adev I used Carthage as well for my above test.

[Michael Welch]

The link in the answer now states this at the top of the page. "IMPORTANT This document is no longer being updated. For the latest information about Apple SDKs, visit the documentation website." Anyone aware where this is being kept up to date? I've had no luck searching for it at the link provided by apple: developer.apple.com/documentation

[Le Mot Juiced]

If you look at your picture of the results of the documentation comment, you can see right under the Declaration there's a section called Discussion that is totally empty. I have found that Swift almost always adds this empty Discussion area, and I've found it close to impossible to find out how to define the Discussion area inside the comments. If you could amend your example to demonstrate that, I think it would help a lot of people avoid the error.

[Le Mot Juiced]

Echoing my comment to @YogendraSingh, I've found that seemingly no matter what you do Swift will automatically add an empty section called Discussion when a documentation comment is shown contextually--you can even see this empty Discussion section in the screenshot he supplied of the contextual pop-up matching the documentation comments he provided. To make matters worse, I've not been able to find out how you actually define the Discussion section in a documentation comment. If at all possible, could you amend your code snippet to include a way to do this?

[Yogendra Singh]

After Summary leave one line and then whatever you write will be the discussion without using any special characters like (- etc). I have edited my answer please have a look.

[Le Mot Juiced]

@YogendraSingh has given his answer, unfortunately when I tried to apply it to a code snippet myself it didn't work and I'm not sure why. If you could update yours in response to his it would be very helpful. Of course we're all busy and I understand if it's a low priority.

[Jia Cheng Sun]

This is a bit late, but check that you have typed 'documentation' in the Completion field (3rd line)