Documentando código (introdução ao DocC)

Por que DocC?

Documentação de funções

/// Adds two integers and returns the sum.
/// - Parameters:
///   - a: First addend.
///   - b: Second addend.
/// - Returns: The sum of `a` and `b`.
/// - Remark: Pure function; no side effects.
func sum(_ a: Int, _ b: Int) -> Int { a + b }

print(sum(2, 3)) // 5

Documentação de tipos e membros

/** A simple counter that tracks a running total.

 Use <code>increment()</code> to add one or a custom amount.
 
 - Note: The type is value-based (a struct).
 */
struct Counter {
    /// Current value of the counter.
    private(set) var value: Int = 0

    /// Increments the counter.
    /// - Parameter amount: How much to add (default is 1).
    mutating func increment(by amount: Int = 1) { value += amount }
}

var c = Counter()
c.increment()
c.increment(by: 3)
print("value =", c.value) // 4

Seção de exemplos

/// Repeats a message a given number of times.
///
/// **Example**
/// ```swift
/// repeatMessage("Hi", times: 2) // prints twice
/// ```
/// - Parameters:
///   - text: Message to print.
///   - times: How many times to print.
func repeatMessage(_ text: String, times: Int) {
    for _ in 0..<times { print(text) }
}

repeatMessage("Hi", times: 2)

Criar a documentação

// Generate documentation for a SwiftPM package (examples):
//   swift package generate-documentation --target MyLib
//   swift package generate-documentation --target MyLib --output-path Docs
//
// Preview in Xcode (DocC):
//   Product > Build Documentation
//
// Tip: keep docs close to code; DocC picks up symbols with /// or /** ... */.

Estilo da documentação

Formas de comentários do DocC

Recapitulação