Documentation Swift : comment écrire de manière claire et efficace

Introduction : pourquoi la documentation pour un projet Swift est une nécessité

Dans le monde du développement iOS et macOS, une documentation de qualité devient souvent le facteur qui sépare un projet amateur d’un produit professionnel. De nombreux développeurs Swift négligent la documentation du code, se fiant à une syntaxe « auto-documentée ». Cependant, lorsque le projet atteint des dizaines de milliers de lignes et que de nouveaux membres rejoignent l’équipe, l’absence de documentation claire se transforme en un problème sérieux.

Apple promeut activement une culture de la documentation : depuis Xcode 13, l’outil DocC (Documentation Compiler) est devenu le standard de facto. Il permet de créer une documentation riche et interactive directement à partir du code source. Dans cet article, nous allons voir comment rédiger correctement la documentation pour les projets Swift — des simples commentaires aux guides de référence complets.

Les bases de la documentation : des commentaires à DocC

Format de documentation en Swift

Swift prend en charge deux formats principaux de commentaires : sur une seule ligne (//) et sur plusieurs lignes (/* */). Pour la documentation, on utilise une syntaxe Markdown étendue, qui commence par /// (pour une seule ligne) ou /** */ (pour plusieurs lignes).

Exemple de base de documentation d’une fonction :

/// Calcule la factorielle d’un nombre.
///
/// Cette fonction utilise une approche récursive pour calculer la factorielle.
/// - Parameter n: Un entier non négatif.
/// - Returns: La factorielle du nombre n.
/// - Warning: La fonction ne gère pas les nombres négatifs.
func factorial(_ n: Int) -> Int {
    guard n >= 0 else { return 0 }
    return n == 0 ? 1 : n * factorial(n - 1)
}

Éléments clés de la documentation

Lors de la rédaction de documentation pour Swift, utilisez les mots-clés (paramètres) suivants :

• - Parameter — description d’un paramètre de fonction
• - Returns — description de la valeur de retour
• - Throws — description des erreurs possibles
• - Warning — avertissements importants
• - Note — remarques supplémentaires
• - Precondition — préconditions pour l’appel
• - Complexity — estimation de la complexité de l’algorithme

DocC : créer une documentation professionnelle

Qu’est-ce que DocC ?

DocC (Documentation Compiler) est un outil d’Apple qui compile la documentation à partir du code source Swift en un site HTML statique. Il prend en charge :

• La génération automatique de documentation pour tous les types public et open
• La liaison d’articles, de guides et de références API
• L’intégration d’images, de diagrammes et d’exemples de code
• Des éléments interactifs : des liens vers d’autres parties de la documentation

Configuration de DocC dans un projet

Pour activer DocC, il suffit d’ajouter un dossier Documentation.docc au projet. À l’intérieur, on crée des fichiers avec l’extension .md. Structure de base :

MyProject/
├── Sources/
│   └── MyProject/
│       └── MyClass.swift
└── Documentation.docc/
    ├── MyProject.md
    └── Articles/
        └── GettingStarted.md

Exemple de documentation pour une classe SwiftUI

/// Vue pour afficher le profil d’un utilisateur.
///
/// Utilisez ce composant pour afficher l’avatar, le nom et des informations brèves.
/// ```swift
/// UserProfileView(userName: "Анна", avatar: "person.circle.fill")
/// ```
public struct UserProfileView: View {
    let userName: String
    let avatar: String
    
    public var body: some View {
        HStack {
            Image(systemName: avatar)
                .resizable()
                .frame(width: 50, height: 50)
            Text(userName)
                .font(.title2)
        }
    }
}

Bonnes pratiques de documentation pour les projets iOS/macOS