How to use Swift documentation comments
IosXcodeSwiftXcode6Documentation GenerationIos Problem Overview
I have a few questions about Swift documentation comments:
-
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. -
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. -
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?
Ios Solutions
Solution 1 - Ios
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 - Ios
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 - Ios
>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 - Ios
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 - Ios
(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
Solution 6 - Ios
Keyboard shortcut in Xcode
option + cmd + /