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.

Do this:

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

Do NOT do this:

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

D2

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

///````
/// let a = 0.0
///````

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
}

D6

Always align the parameter descriptions to the longest parameter name.

Do this:

/// - parameter red:              The red value...
/// - parameter anotherParameter: The green value...

Do NOT do this:

/// - parameter red: The red value...
/// - parameter anotherParameter: The green value...

D7

Remove spaces between a doc0 block and the method it is documenting.

Do this:

/// An example method
func exampleMethod() {
}

Do NOT do this:

/// An example method

func exampleMethod() {
}

##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)
}

##Notes The current standards for C4 require you to use the following:

• Description
• Code example (default to having one, where applicable it can be skipped)
• parameters
• returns
• throws

Apple's Markup Formatting Reference lists a lot of other options like:

• author:
• version:
• etc:

For now, we are omitting everything other than the 5 options specified above.