Sviluppo e perfezionamento della documentazione

La documentazione è fondamentale per il successo del tuo progetto. Non solo spiega come funziona il codice, ma aiuta anche gli sviluppatori a comprendere meglio le caratteristiche e le funzionalità delle applicazioni. Lo sviluppo e il perfezionamento di documentazione di alta qualità possono rafforzare il processo di sviluppo di software, mantenere software eccellenti e favorire il trasferimento delle conoscenze tra sviluppatori.

Esistono due categorie di documentazione: la documentazione all'interno del codice e quella di supporto relativa al codice. La prima si presenta sotto forma di commenti. La seconda può consistere in file README e documenti esterni. Non è raro che gli sviluppatori considerino la documentazione come un sovraccarico, poiché il codice stesso è facile da capire. Ciò potrebbe valere i progetti piccoli, ma la documentazione è fondamentale per i progetti su larga scala che vedono coinvolti più team.

È consigliabile che l'autore del codice scriva la documentazione poiché ne conosce bene le funzionalità. Gli sviluppatori possono avere difficoltà a gestire il sovraccarico aggiuntivo derivante dalla gestione di una documentazione di supporto a sé stante. Per superare questo ostacolo, possono aggiungere all'interno del codice commenti che possono essere estratti in modo automatico, così che tutte le versioni del codice e della documentazione siano sincronizzate.

Esistono diversi strumenti per aiutare gli sviluppatori a estrarre commenti dal codice e generare la relativa documentazione. Questa guida è considerata lo strumento preferito per i AWS CDK costrutti. TypeDoc

Perché è necessaria la documentazione del codice per AWS CDK i costrutti

AWS CDK i costrutti comuni vengono creati da più team di un'organizzazione e condivisi tra diversi team per essere utilizzati. Una buona documentazione aiuta gli utenti della libreria di costrutti a integrarli facilmente e a costruire la propria infrastruttura con il minimo sforzo. Mantenere sincronizzati tutti i documenti non è semplice. Ti consigliamo di mantenere il documento all'interno del codice, che verrà estratto utilizzando la TypeDoc libreria.

Utilizzo TypeDoc con la AWS Construct Library

TypeDoc è un generatore di documenti per TypeScript. È possibile TypeDoc utilizzarlo per leggere i file TypeScript sorgente, analizzare i commenti in tali file e quindi generare un sito statico che contiene la documentazione per il codice.

Il codice seguente mostra come eseguire l'integrazione TypeDoc con la AWS Construct Library e quindi aggiungere i seguenti pacchetti nel package.json file in. devDependencies

{

  "devDependencies": {
   
    "typedoc-plugin-markdown": "^3.11.7",
    "typescript": "~3.9.7"
  },
  
}

Per aggiungere typedoc.json nella cartella della libreria CDK, utilizza il codice seguente.

{
    "$schema": "https://typedoc.org/schema.json",
    "entryPoints": ["./lib"],
}

Per generare i file README, esegui il npx typedoc comando nella directory principale del progetto della libreria di AWS CDK costruzioni.

Il seguente documento di esempio è generato da. TypeDoc

Per ulteriori informazioni sulle opzioni di TypeDoc integrazione, consulta Doc Comments nella TypeDoc documentazione.