The documentation blocks come in a predetermined structure. Most of your documentation will use the following five sections:
- Summary: What your function does, always at the top of the documentation. This is also the first paragraph of your documentation comment.
- Discussion: Additional information about your function. This will be rendered with all other paragraphs, except the first one.
- Returned values: You can add more information about what your function returns by starting your line with Returns:.
- Parameters: Each parameter of your function can be described with Parameter <name>:.
- Thrown errors: You can provide additional information about the errors your method can throw by using Throws:.
The Parameters section also supports more than one parameter, as you may imagine. To document them all, you can use an unordered list as in the following example:
/**
Compute the slope between two points
This function calculate the slope between two points in a carthesian plane
- Returns:
the slope between the points (x0, y0) and (x1, y1)
- Parameters:
- x0: the x coordinate for the first point
- y0: the y coordinate for the first point
- x1: the x coordinate for the second point
- y1: the y coordinate for the second point
- Throws: SlopeError.infinite when y1 - y0 === 0: ie the slope is infinite
*/
func slope(x0: Double, y0: Double, x1: Double, y1: Double) throws -> Double {
guard y1 - y0 != 0 else {
throw SlopeError.inifinite
}
return x1 - x0 / y1 - y0
}
Keeping example usages for each methods, when not obvious or complicated, is also a good idea. Luckily, Markdown has us covered with different techniques to delimit blocks of code. The best of all? You get free a gorgeous rendering of your code examples for everyone to read during their implementation – for free! Code samples come in two flavours:
- For simple lines or single elements, you can use `, which will render within your current block but with a monospace font.
- For multiline code examples, you can use two formats:
- Four-spaces indents
- Triple backticks ```
My personal preference is the triple backticks, as I find them more readable and predictable compared to the four-space indents. Try to determine what fits your needs and preferences.
Have a look at the following example from the preceding code:
/**
Compute the slope between two points
This function calculate the slope between two points in a carthesian plane
- Returns:
the slope between the points (x0, y0) and (x1, y1)
- Parameters:
- x0: the x coordinate for the first point
- y0: the y coordinate for the first point
- x1: the x coordinate for the second point
- y1: the y coordinate for the second point
- Throws: SlopeError.infinite when y1 - y0 === 0: ie the slope is infinite
```
const flat = try! slope(x0: 2, y0: 1, x1: 5, y1: 1)
flat == 0
```
*/
func slope(x0: Double, y0: Double, x1: Double, y1: Double) throws -> Double {
guard x1 - x0 != 0 else {
throw SlopeError.inifinite
}
return y1 - y0 / x1 - x0
}
The preceding example will render nicely in the Quick Help:
