Développer et affiner la documentation - AWS Conseils prescriptifs

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. La documentation associée relative au code peut se composer des fichiers README 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 ajouter typedoc.json dans le dossier de la bibliothèque CDK, utilisez le code suivant.

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

Pour générer les fichiers README, 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.


                    Exemple de  TypeDoc  document

Pour plus d'informations sur les options TypeDoc d'intégration, consultez les commentaires relatifs aux documents dans la TypeDoc documentation.