Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
Développer et affiner la documentation
La documentation est essentielle à la réussite de votre projet. Non seulement la documentation explique le fonctionnement de votre code, mais elle aide également les développeurs à mieux comprendre les caractéristiques et les fonctionnalités de vos applications. Le développement et le perfectionnement d'une documentation de haute qualité peuvent renforcer le processus de développement logiciel, maintenir des logiciels de haute qualité et faciliter le transfert de connaissances entre les développeurs.
Il existe deux catégories de documentation : la documentation contenue dans le code et la documentation associée relative au code. La documentation contenue dans le code se présente sous forme de commentaires. Les documents de support relatifs au code peuvent être README des fichiers et des documents externes. Il n'est pas rare que les développeurs considèrent la documentation comme une surcharge, car le code lui-même est facile à comprendre. Cela peut être vrai pour les petits projets, mais la documentation est cruciale pour les projets de grande envergure impliquant plusieurs équipes.
Il est recommandé que l'auteur du code rédige la documentation, car il en comprend bien les fonctionnalités. Les développeurs peuvent avoir du mal à supporter la surcharge liée à la maintenance de la documentation associée distincte. Pour relever ce défi, les développeurs peuvent ajouter les commentaires dans le code et ces commentaires peuvent être extraits automatiquement afin que chaque version du code et de la documentation soit synchronisée.
Il existe différents outils pour aider les développeurs à extraire les commentaires du code et à générer la documentation correspondante. Ce guide se concentre sur le fait TypeDoc qu'il s'agit de l'outil préféré pour AWS CDK les constructions.
Pourquoi la documentation du code est requise pour les AWS CDK constructions
AWS CDK les concepts communs sont créés par plusieurs équipes au sein d'une organisation et partagés entre différentes équipes à des fins d'utilisation. Une bonne documentation aide les utilisateurs de la bibliothèque de constructions à intégrer facilement les constructions et à créer leur infrastructure avec un minimum d'effort. La synchronisation de tous les documents est une tâche conséquente. Nous vous recommandons de conserver le document dans le code, qui sera extrait à l'aide de la TypeDoc bibliothèque.
Utilisation TypeDoc avec la bibliothèque AWS Construct
TypeDoc est un générateur de documents pour TypeScript. Vous pouvez l'utiliser TypeDoc pour lire vos fichiers TypeScript source, analyser les commentaires contenus dans ces fichiers, puis générer un site statique contenant la documentation de votre code.
Le code suivant vous montre comment intégrer TypeDoc la bibliothèque AWS Construct, puis comment ajouter les packages suivants dans votre package.json fichierdevDependencies.
{ "devDependencies": { "typedoc-plugin-markdown": "^3.11.7", "typescript": "~3.9.7" }, }
Pour l'ajouter typedoc.json dans le dossier de CDK bibliothèque, utilisez le code suivant.
{ "$schema": "https://typedoc.org/schema.json", "entryPoints": ["./lib"], }
Pour générer les README fichiers, exécutez la npx typedoc commande dans le répertoire racine du projet de bibliothèque de AWS CDK construction.
L'exemple de document suivant est généré par TypeDoc.
Pour plus d'informations sur les options TypeDoc d'intégration, consultez les commentaires
