You can use // MARK:
There has also been discussion that liberal use of class extensions might be a better practice anyway. Since extensions can implement protocols, you can e.g. put all of your table view delegate methods in an extension and group your code at a more semantic level than #pragma mark
is capable of.
tl;dr: Use the class constant approach if you are using Swift 1.2 or above and the nested struct approach if you need to support earlier versions.
From my experience with Swift there are three approaches to implement the Singleton pattern that support lazy initialization and thread safety.
Class constant
class Singleton {
static let sharedInstance = Singleton()
}
This approach supports lazy initialization because Swift lazily initializes class constants (and variables), and is thread safe by the definition of let
. This is now officially recommended way to instantiate a singleton.
Class constants were introduced in Swift 1.2. If you need to support an earlier version of Swift, use the nested struct approach below or a global constant.
Nested struct
class Singleton {
class var sharedInstance: Singleton {
struct Static {
static let instance: Singleton = Singleton()
}
return Static.instance
}
}
Here we are using the static constant of a nested struct as a class constant. This is a workaround for the lack of static class constants in Swift 1.1 and earlier, and still works as a workaround for the lack of static constants and variables in functions.
dispatch_once
The traditional Objective-C approach ported to Swift. I'm fairly certain there's no advantage over the nested struct approach but I'm putting it here anyway as I find the differences in syntax interesting.
class Singleton {
class var sharedInstance: Singleton {
struct Static {
static var onceToken: dispatch_once_t = 0
static var instance: Singleton? = nil
}
dispatch_once(&Static.onceToken) {
Static.instance = Singleton()
}
return Static.instance!
}
}
See this GitHub project for unit tests.
Best Answer
Documentation comments are supported natively in Xcode, producing smartly rendered documentation in Quick Help (both in the popover when ⌥-clicking symbols, and in the Quick Help Inspector ⌥⌘2).
Symbol documentation comments are now based on the same Markdown syntax used by rich playground comments, so a lot of what you can do in playgrounds can now be used directly in source code documentation.
For full details of the syntax, see Markup Formatting Reference. Note that there are some discrepancies between the syntax for rich playground comments & symbol documentation; these are pointed out in the document (e.g. block quotes can only be used in playgrounds).
Below is an example and a list of the syntax elements that currently work for symbol documentation comments.
Updates
Xcode 7 beta 4 ~ Added "
- Throws: ...
" as a top-level list item which appears alongside parameters and return descriptions in Quick Help.Xcode 7 beta 1 ~ Some significant changes to syntax with Swift 2 - documentation comments now based on Markdown (same as playgrounds).
Xcode 6.3 (6D570) ~ Indented text is now formatted as code blocks, with subsequent indentations being nested. It doesn't appear to be possible to leave a blank line in such a code block - trying to do so results in the text being tacked onto the end of the last line with any characters in it.
Xcode 6.3 beta ~ Inline code can now be added to documentation comments using backticks.
Example for Swift 2
Syntax for Swift 2 (based on Markdown)
Comment Style
Both
///
(inline) and/** */
(block) style comments are supported for producing documentation comments. While I personally prefer the visual style of/** */
comments, Xcode's automatic indentation can ruin formatting for this comment style when copying/pasting as it removes leading whitespace. For example:When pasting, the code block indentation is removed and it is no longer rendered as code:
For this reason, I generally use
///
, and will use it for the rest of the examples in this answer.Block Elements
Heading:
or
Subheading:
or
Horizontal rule:
Unordered (bulleted) lists:
You can also use
+
or*
for unordered lists, it just has to be consistent.Ordered (numbered) lists:
Code blocks:
An indentation of at least four spaces is required.
Inline Elements
Emphasis (italics):
Strong (bold):
Note that you cannot mix asterisks (
*
) and underscores (_
) on the same element.Inline code:
Links:
Images:
The URL can be either a web URL (using "http://") or an absolute file path URL (I can't seem to get relative file paths to work).
The URLs for links and images can also be separated from the inline element in order to keep all URLs in one, manageable place:
Keywords
In addition to the Markdown formatting, Xcode recognises other markup keywords to display prominently in Quick Help. These markup keywords mostly take the format
- <keyword>:
(the exception isparameter
, which also includes the parameter name before the colon), where the keyword itself can be written with any combination of uppercase/lowercase characters.Symbol Section keywords
The following keywords are displayed as prominent sections in the help viewer, below the "Description" section, and above the "Declared In" section. When included, their order is fixed as displayed below even though you can include them in whatever order you like in your comments.
See the fully documented list of section keywords and their intended uses in the Symbol Section Commands section of the Markup Formatting Reference.
Alternatively, you can write each parameter this way:
Symbol Description Field keywords
The following list of keywords are displayed as bold headings in the body of the "Description" section of the help viewer. They will appear in whatever order you write them in, as with the rest of the "Description" section.
Full list paraphrased from this excellent blog article by Erica Sadun. Also see the fully documented list of keywords and their intended uses in the Symbol Description Field Commands section of the Markup Formatting Reference.
Attributions:
Availability:
Admonitions:
Development State:
Implementation Qualities:
Functional Semantics:
Cross Reference:
Exporting Documentation
HTML documentation (designed to mimic Apple's own documentation) can be generated from inline documentation using Jazzy, an open-source command-line utility.
Console example taken from this NSHipster article