Documenting Standards

Documenting Standards

This document describes the guidelines and specifications for documenting C4 code base. Anything that doesn't follow these guidelines will be rejected. Please read this carefully before contributing.

Documenting style

The basic rule is "follow the current style". We want the documentation to follow the same formatting style throughout. In particular:

D1

Use the triple-slash markers /// to mark documentation, rather than the block quote asterisk /** */. The triple-slash should be followed by a single space.

///The example function does nothing, and takes no variables.
///
///func example() {
///}

D2

Code blocks should be wrapped with 4 ticks (above and below):

///````
///func example() {
///}
///````

D3

Always default to adding a code example. In general, a code example is necessary if the use of the function is ambiguous to a new user. Code examples are necessary for simple use cases.

For example, the C4Log() function requires some example code because it can have multiple kinds of input.

/// Prints a string to the console. Replacement for the noisy NSlog.
///
/// ````
/// C4Log("A message")
/// C4Log(0)
/// ````
/// - parameter string: A formatted string

However, the description of something like an enum does not require an example:

/// Rules for determining how a path gets filled with color.
/// 
/// ````
/// public enum FillRule {
/// }
/// ````

D4

Use the - parameter param: syntax instead of Swift's new - parameters: syntax.

Do this:

/// - parameter red: The red value for the new color [0.0 ... 1.0]
/// - parameter green: The green value for the new color [0.0 ... 1.0]

Do NOT do this:

/// - parameters:
///     - red: The red value for the new color [0.0 ... 1.0]
///     - green: The green value for the new color [0.0 ... 1.0]

D5

When a function returns an object or variable, use the returns declaration.

/// An example method that returns an integer
/// 
/// - returns: An integer, defaults to 0.
func example() -> Int {
    return 0
}

##Full Example The following is a full example of a documented function:

/// An example method that returns an ExampleObject
///
/// ````
/// let eo = exampleMethod(1.0, "myImage", 2)
/// ````
///
/// - parameter a:     CGFloat
/// - parameter b: String
/// - parameter c: Int
///
/// - returns: an new ExampleObject
func exampleMethod(a: CGFloat, b: String, c: Int) {
    return ExampleObject(a, b, c)
}