Milestone 5: package, moduli e documentazione

Un progetto finale serio non è solo codice che gira. È codice che un’altra persona può aprire, capire, eseguire e modificare.

Questa milestone riguarda:

• struttura SwiftPM;
• target;
• access control;
• README;
• DocC;
• esempi;
• comandi di verifica;
• pulizia dell’API pubblica.

Package layout

Esempio:

Package.swift
README.md
PROJECT.md
Sources/
  StoryDomain/
  StoryApplication/
  StoryInfrastructure/
  StoryCLI/
  StoryUI/
Tests/
  StoryDomainTests/
  StoryApplicationTests/
  StoryInfrastructureTests/
Docs/

Se il progetto è piccolo, puoi ridurre:

Sources/
  StoryKit/
  StoryCLI/
Tests/
  StoryKitTests/

La struttura deve servire la comprensione, non impressionare.

Package manifest

let package = Package(
  name: "StoryKit",
  platforms: [
    .macOS(.v14),
    .iOS(.v17)
  ],
  products: [
    .library(name: "StoryKit", targets: ["StoryKit"]),
    .executable(name: "story", targets: ["StoryCLI"])
  ],
  dependencies: [
    .package(url: "https://github.com/apple/swift-argument-parser", from: "1.5.0")
  ],
  targets: [
    .target(name: "StoryKit"),
    .executableTarget(
      name: "StoryCLI",
      dependencies: [
        "StoryKit",
        .product(name: "ArgumentParser", package: "swift-argument-parser")
      ]
    ),
    .testTarget(name: "StoryKitTests", dependencies: ["StoryKit"])
  ]
)

Le piattaforme minime sono una scelta progettuale.

Access control

Rivedi ogni public.

Domande:

• serve davvero fuori dal modulo?
• il nome è stabile?
• il tipo espone dettagli interni?
• questa API può evolvere?
• l’errore è documentato?

Esempio:

public struct StoryClient: Sendable {
  private let repository: StoryRepository

  public init(configuration: StoryClientConfiguration) {
    self.repository = RemoteStoryRepository.live(configuration: configuration)
  }
}

Non esporre RemoteStoryRepository se l’utente deve usare solo StoryClient.

README

README minimo:

# StoryKit

StoryKit is a Swift package for searching and caching stories from a remote API.

## Requirements

- Swift 6.x
- macOS 14 or iOS 17

## Quick start

swift build
swift test
swift run story search "swift"

## Architecture

Domain -> Application -> Infrastructure -> CLI/UI

## Testing

The test suite avoids real network calls and uses stub HTTP clients.

Il README deve permettere a qualcuno di partire in pochi minuti.

DocC

Se hai API pubbliche, aggiungi DocC.

Sources/
  StoryKit/
    StoryKit.docc/
      StoryKit.md
      Tutorials/

StoryKit.md:

# StoryKit

Search, cache and present stories with a small Swift domain model.

## Overview

Use ``StoryClient`` for high-level access or ``StoryRepository`` when you need custom infrastructure.

DocC deve raccontare come usare il package, non solo generare simboli.

Commenti API

/// Searches stories using a validated query.
///
/// The repository may return cached data depending on the implementation.
public protocol StoryRepository: Sendable {
  func search(query: SearchQuery) async throws -> [Story]
}

Commenta contratti, errori e comportamenti non ovvi.

Examples

Un esempio compilabile vale più di molte spiegazioni.

let client = StoryClient.live()
let stories = try await client.search("swift concurrency")

Se l’esempio non compila nella tua testa, probabilmente l’API è scomoda.

Comandi di verifica

Nel README includi:

swift format lint --recursive Sources Tests
swift test
swift build -c release
swift package generate-documentation

Usa solo comandi che il progetto supporta davvero.

Se non hai configurato swift-format, non fingere che esista.

API review personale

Fai una review dell’API pubblica:

Story
SearchQuery
StoryClient
StoryRepository
StoryError
StoryClientConfiguration

Per ogni simbolo chiedi:

• perché è pubblico?
• è documentato?
• ha test?
• il nome comunica intenzione?
• può essere usato male facilmente?

Checklist

La milestone 5 è completa quando:

• Package.swift è leggibile;
• target e prodotti hanno responsabilità chiare;
• access control è intenzionale;
• README spiega avvio e architettura;
• DocC documenta il nucleo pubblico;
• esempi sono realistici;
• comandi di build/test sono indicati;
• API pubblica non espone dettagli inutili.

Esercizio

Prepara la consegna tecnica:

1. rivedi Package.swift;
2. rimuovi public inutili;
3. scrivi README;
4. aggiungi DocC overview;
5. documenta 5 simboli pubblici;
6. aggiungi sezione test;
7. aggiungi sezione architettura;
8. verifica swift test.

Obiettivo: un revisore deve poter capire progetto, comandi e scelte senza chiederti una call.