Swift - Internal Documentation
The recommended way to write documentation comments in Xcode is to place the text cursor on the declaration and press Command + Option + /. This will automatically generate the correct format with placeholders to be filled in.
General format
Documentation comments are written using the format where each line is preceded by a triple slash (///). Javadoc-style block comments (/** ... */) are not permitted.
Example:
/// Returns the numeric value of the given digit represented as a Unicode scalar.
func numericValue(of digit: UnicodeScalar, radix: Int = 10) -> Int {
// ...
}
Note that with the double-slash we are still writing comments, but those are not considered to build the internal documentation.
Parameter, Returns, and Throws Tags
Clearly document the parameters, return value, and thrown errors of functions using the Parameter(s), Returns, and Throws tags, in that order. None ever appears with an empty description. When a description does not fit on a single line, continuation lines are indented 2 spaces in from the position of the hyphen starting the tag.
Example with single parameter (note the singular form):
/// Returns the output generated by executing a command.
///
/// - Parameter command: The command to execute in the shell environment.
/// - Returns: A string containing the contents of the invoked process's
/// standard output.
func execute(command: String) -> String {
// ...
}
Example with multiple parameters (note the plural form):
/// Returns the output generated by executing a command with the given string
/// used as standard input.
///
/// - Parameters:
/// - command: The command to execute in the shell environment.
/// - stdin: The string to use as standard input.
/// - Returns: A string containing the contents of the invoked process's
/// standard output.
func execute(command: String, stdin: String) -> String {
// ...
}