Générateur de documentation C# ?

Question

Existe-t-il un générateur de documentation pour C# ? Par exemple, quelque chose qui mettrait la documentation xml-ish juste au-dessus des déclarations de méthodes/classes ? Existe-t-il un outil ou est-il caché quelque part dans VS 2008 ?

Answer 1

Une liste complète :

Options gratuites et/ou open source

• Château de sable . Peut-être l'un des choix les plus populaires. Sandcastle produit une documentation précise, complète et de style MSDN en réfléchissant sur les assemblages sources et en intégrant éventuellement des commentaires de documentation XML. Sandcastle présente les caractéristiques clés suivantes : fonctionne avec ou sans commentaires rédigés, supporte les génériques et .NET. (Note : Sandcastle a changé de mains pour devenir SHFB. Pour l'ancien projet Sandcastle, allez à ici .)

• GhostDoc . Probablement deuxième en popularité après Sandcastle. GhostDoc est un module complémentaire gratuit pour Visual Studio qui génère automatiquement des commentaires de documentation XML pour C#. Soit en utilisant la documentation existante héritée des classes de base ou des interfaces implémentées, soit en déduisant des commentaires à partir du nom et du type des méthodes, propriétés ou paramètres, par exemple. Basically it generates the /// comments above the methods, class, etc for you.

• Doxygen . Il fonctionne avec de nombreux langages de programmation. Il peut générer un navigateur de documentation en ligne (en HTML) et/ou un manuel de référence hors ligne (en LATEX) à partir d'un ensemble de fichiers sources documentés. (Ce générateur est mon choix personnel).

• Docu . Un générateur de documentation pour .Net qui n'est pas compliqué, gênant ou difficile à utiliser. À partir d'un assemblage et du XML généré par Visual Studio, Docu peut produire un site Web complet de documentation en une seule commande.

• Nocco . Nocco est un générateur de documentation rapide et sale, de style programmation littéraire. C'est un portage C# de Docco . Nocco produit du HTML qui affiche vos commentaires à côté de votre code. Les commentaires sont passés par Markdown, et le code est mis en évidence en utilisant la coloration syntaxique google-code-prettify.

• Visual Studio générera pour vous des balises XML de documentation de modèle en tapant /// au début de la méthode, de la variable, etc.

• Docs naturels . Natural Docs est un générateur de documentation open-source pour plusieurs langages de programmation. Vous documentez votre code dans une syntaxe naturelle qui se lit comme de l'anglais ordinaire. Natural Docs scanne alors votre code et construit une documentation HTML de haute qualité à partir de celui-ci.

• Documenteur en direct . Le Live Documenter n'est pas seulement un autre outil de documentation .NET, il est différent. Il fonctionne en affichant la documentation en direct pour votre projet. Plutôt qu'une vieille copie statique périmée. Le Live Documenter vous permet de lire vos commentaires, comme un livre. Toujours en direct. (Gratuit pour une utilisation non commerciale)

• NDoc3 Mention notable - mais ce projet semble être en voie d'extinction. .

Options non gratuites

• Document ! X . Document ! X est une combinaison d'un outil de documentation .NET automatisé et d'un environnement de création de documentation complet qui peut être utilisé pour créer une documentation dotnet précise et de qualité professionnelle pour les assemblages créés avec n'importe quel langage .NET (C#, Visual Basic, C++/CLI, etc.). (A partir de 468 USD)

• VSdocman . VSdocman est un outil de documentation d'API ultime pour tout développeur Visual Studio - que vous créiez une bibliothèque de classes, un composant, un contrôle, une application, un dispositif intelligent ou un site Web (ASP .NET). (A partir de 229 USD par licence)

• Atomineer Pro . Cette extension pour Visual Studio offre une génération et une mise à jour inégalées des commentaires de la documentation de code, un habillage intelligent du texte dans les commentaires, des aides à la saisie en direct pour faciliter l'édition des commentaires, des outils pour convertir rapidement la documentation existante dans de nouveaux formats, une commande pour aligner instantanément le code (comme les affectations, les paramètres et les données tabulaires) dans des colonnes, ainsi que plusieurs commandes pratiques pour le contournement, la génération de code et le presse-papiers. (A partir de 40 USD par licence)

• TwinText . Un autre générateur de documents HTML de type code-commentaire. Ne nécessite pas de balisage spécial dans les commentaires. Permet de personnaliser facilement l'apparence du document. (169 USD par licence)

• Doc-O-Matic . Prend le code source et les commentaires, ajoute des sujets conceptuels et des entrées externes et produit de la documentation à partir de ceux-ci. Génère de l'aide HTML, PDF, Help 2, Help 3 pour l'aide Web et l'aide Windows. (49 USD)

Answer 2

Je vous recommande de jeter un coup d'œil à Château de sable . Il génère la documentation des bibliothèques de classes à partir des assemblages .NET et des fichiers de documentation XML générés par le compilateur C#. Vous pouvez utiliser les outils GUI de SandCastle, SHFB ou DocProject ce qui facilitera complètement le processus de génération de documents.

Jetez également un coup d'œil aux recommandations et aux autorisations Balises XML .

Mise à jour : Je suis d'accord avec le commentaire de Matt, NDoc est presque un projet mort et rappelez-vous que vous pouvez également utiliser l'ancien système Méthode XSLT .

Answer 3

Vous pouvez commencer un commentaire par /// juste au-dessus d'une classe ou d'un membre de classe et VS insérera des balises de documentation de modèle pour vous.

Answer 4

J'aime bien GhostDoc

GhostDoc est un module complémentaire gratuit pour Visual Studio qui génère automatiquement des documents XML pour C#. Soit en utilisant la documentation existante héritée des classes de base ou des interfaces implémentées, soit en déduisant des commentaires à partir du nom et du type des méthodes, des propriétés ou des paramètres, par exemple.

En gros, il génère pour vous les commentaires /// au-dessus des méthodes, des classes, etc. Ils ne sont pas parfaits mais constituent un bon point de départ.

Answer 5

Conformément à la suggestion de Ray, GhostDoc est pratique, bien qu'il puisse conduire à des docs passe-partout sans substance si les développeurs sont paresseux.

Château de sable était à l'origine supporté par Microsoft, mais est maintenant maintenu par SHFB . Vous documentez en utilisant la norme Balises C# . Il dispose de plusieurs formats de sortie et d'une grande flexibilité. Il suffit de donner beaucoup de RAM à la machine sur laquelle vous créez des documents.

Je recommande SHFB pour faciliter la vie de Sandcastle. Il s'inspire de NDoc et fonctionne à partir d'une interface graphique ou d'une ligne de commande.