Swift Documentation Quick Guide
Posted By : Aditya Kumar Sharma | 16-May-2018
Documenting the code is a very important task for each and every developer. Although it makes the development process little bit slow. But for good
Xcode 7 introduced a powerful Markdown syntax for rich text formatting in the documentation. Let’s have a look at it:
Symbol Documentation
There are 4 sections, out of which description is always included in the documentation.
- Description
- Parameters
- Returns
- Throws
Description
To add any comment before a function, variable or a class. Just use triple-slash for single line comments. Or comment
/// Some introductory description for the method or the function
/// of the function.
/**
What this function do?
*/
func someSoCalledFunction(name: String) -> Bool {
return false
}
How it will appear in Quick-Help:
Parameters Section
Generally, all keyword starts with hyphen and end with the colon. We can document parameters with two ways either by using the parameter section or individual parameter fields. Eg:
/**
Another description of useful function
- parameters:
- isAlpha: Describe the isAlpha param
- isBeta: Describe the isBeta param
*/
func doSomething(isAlpha: Bool, isBeta: Bool) { }
How it will appear in Quick-Help:
/**
Another description of useful function
- parameter isAlpha: Describe the isAlpha param
- parameter isBeta: Describe the isBeta param
*/
func doSomething1(isAlpha: Bool, isBeta: Bool) { }
How it will appear in Quick-Help:
Throws Section
If a function or method that contains throws section, it means it throws an error:
/// Some method which performs some work and
/// also throws error.
/// - Throws: SomeError you might want to catch
func someDemoFunction() throws -> Bool {
How it will appear in Quick-Help:
Returns section
If a function returns a value it contains return section:
/// Some method which performs some work and
/// also throws error.
/// - Returns: return value that you want to use
/// - Throws: SomeError you might want to catch
func someDemoFunction() throws -> Bool {
return true
}
How it will appear in Quick-Help:
Other Keywords
There is a long list of the keyword, some of them are:
/**
Other **Keywords** available for documentation
- Attention: Watch out for this!
- Author: Aditya Sharma
- Authors:
Aditya Sharma1
Aditya Sharma2
- Bug: crashing for alphanumeric case
- Complexity: O(log n^2) approx
- Copyright: 2018 Copyright
- Date: Jan 1, 2018
- experiment: have a try
- important: know this
- invariant: something
- Note: foo foo foo
- Precondition: value should not be nil
- Postcondition: Result successful
- Remark: something else
- Requires: iOS 11, xCode 9
- seealso: something else
- Since: iOS 11
- Todo: Need to complete it
- Version: 1.0.2
- Warning: Deprecated
*/
Have a happy documenting to all!
Cookies are important to the proper functioning of a site. To improve your experience, we use cookies to remember log-in details and provide secure log-in, collect statistics to optimize site functionality, and deliver content tailored to your interests. Click Agree and Proceed to accept cookies and go directly to the site or click on View Cookie Settings to see detailed descriptions of the types of cookies and choose whether to accept certain cookies while on the site.
About Author
Aditya Kumar Sharma
Aditya is a bright iOS developer, have knowledge of objective C, swift, swift 3, JSON, Core data and iPhone development. Apart from that he loves to travel and explore new things.