DocC: documentare framework e package

DocC, Documentation Compiler, è lo strumento dell’ecosistema Swift per produrre documentazione ricca per framework e package.

La documentazione professionale non è un README enorme. È un insieme di:

• commenti sui simboli pubblici;
• articoli concettuali;
• tutorial;
• esempi;
• riferimenti navigabili.

Commenti di documentazione

Usa /// sui simboli pubblici:

/// Applica coupon a carrelli e calcola il totale finale.
public struct CouponEngine {
  /// Applica un coupon al carrello indicato.
  ///
  /// - Parameters:
  ///   - coupon: Il coupon da applicare.
  ///   - carrello: Il carrello di partenza.
  /// - Returns: Un carrello aggiornato con lo sconto applicato.
  /// - Throws: `ErroreCoupon` se il coupon non è valido.
  public func applica(_ coupon: Coupon, a carrello: Carrello) throws -> Carrello {
    ...
  }
}

Non scrivere commenti che ripetono il nome. Spiega contratto, fallimenti e casi limite.

Cosa documentare

Documenta:

• API pubbliche;
• errori;
• initializer con invarianti;
• tipi di dominio centrali;
• esempi d’uso;
• comportamenti non ovvi;
• thread-safety o actor isolation.

Non documentare ogni proprietà ovvia se il nome è chiaro.

Documentation catalog

Un package può avere un catalogo DocC:

Sources/
  CouponKit/
    CouponEngine.swift
    CouponKit.docc/
      CouponKit.md
      Articles/
        GettingStarted.md

Il catalogo contiene pagine Markdown che estendono la documentazione dei simboli.

Pagina introduttiva

Esempio CouponKit.md:

# CouponKit

Model and apply coupons with strongly typed Swift APIs.

## Overview

Use `CouponEngine` to validate and apply coupons to carts.

DocC collega testo è simboli.

Articoli

Gli articoli spiegano concetti:

# Modeling Coupon Rules

Learn how CouponKit represents coupon constraints using typed rules.

Sono utili per:

• architettura;
• scelte di dominio;
• guide introduttive;
• migrazione;
• esempi completi.

Generare documentazione

I comandi variano in base al flusso e alla piattaforma, ma l’idea è:

swift package generate-documentation

Oppure usare strumenti DocC diretti per convertire cataloghi.

Il punto didattico: la documentazione deve poter essere generata, non restare solo nei commenti del codice.

DocC in Swift 6.3

Swift 6.3 ha aggiunto capacità sperimentali a DocC, tra cui output Markdown per generare versioni Markdown delle pagine oltre al rendering standard. Questo rafforza l’idea che la documentazione sia un artefatto della toolchain, non un file separato dimenticato.

Documentare errori

/// Errori prodotti durante la validazione di un coupon.
public enum ErroreCoupon: Error, Equatable {
  /// Il totale del carrello non raggiunge la soglia richiesta.
  case carrelloSottoMinimo(richiesto: Int, attuale: Int)
}

Gli errori sono parte dell’API. Devono essere comprensibili.

Checklist DocC

Prima di pubblicare un package:

• ogni tipo pubblico centrale ha documentazione;
• ogni funzione throws spiega gli errori;
• gli initializer validanti spiegano invarianti;
• esiste una pagina introduttiva;
• esiste almeno un articolo “Getting Started”;
• gli esempi compilano concettualmente;
• la documentazione si genera in CI o localmente.

Esercizio

Per CouponKit:

1. documenta CouponEngine;
2. documenta ErroreCoupon;
3. crea un catalogo CouponKit.docc;
4. aggiungi una pagina introduttiva;
5. aggiungi un articolo “Getting Started”;
6. genera la documentazione.

Poi leggi la documentazione come se fossi un utente esterno: cosa manca per iniziare?