Visual Studio avec DoxyGen pour la documentation, ou devrions-nous utiliser autre chose?

Question

Nous sommes actuellement à DoxyGen pour documenter le code écrit en C/C++, PHP et Java. Pour avoir un environnement cohérent, il serait bien de les utiliser pour C# la documentation.

Cependant, nous nous demandons:

• Voyez-vous des avantages dans la documentation générée mise en page ou de la structure à l'aide de quelque chose d'autre que DoxyGen? Nous sommes la génération de la documentation pour les développeurs externes qui ont de l'expérience avec C# et de la .NET plate-forme. Peut-être qu'ils sont habitués à un certain format de documentation?
• Comment bien intégré peut DoxyGen être avec Visual Studio? Est-il quelque chose qui permet d'un seul clic de génération de documentation à partir de l'intérieur de l'IDE?
• Un autre système de documentation des plus intégré à Visual Studio?

Answer 1

La valeur par défaut de documenter le code C# dans Visual Studio est par les commentaires de documentation XML. À mon avis c'est la meilleure voie à suivre pour le code C# parce que le soutien pour ce qui est déjà intégré dans Visual Studio (balise de commentaire saisie semi-automatique, en garde manquants ou mal orthographié paramètres, ...). Document une méthode, il suffit de taper trois barres obliques (///) devant le corps de la méthode, et Visual Studio va insérer un commentaire vide modèle qu'il vous faut pour remplir, comme suit:

/// <summary>
/// 
/// </summary>
/// <param name="bar"></param>
private void Foo(int bar)
{
    // ...
}

Vous pouvez configurer Visual Studio pour générer un fichier XML à partir de toutes les observations, qui serait ensuite introduit dans un générateur de documentation comme des Châteaux de sable. Si vous souhaitez utiliser Doxygen, ce n'est pas un problème car il prend en charge l'analyse des commentaires XML.

Pour résumer: je vous recommande d'utiliser XML commentaires sur spécial Doxygen commentaires pour le code C#. De cette façon, vous disposez de toutes les options. Vous pouvez générer la documentation dans la norme Doxygen mise en page de votre organisation est familier avec (c'est parce que ... Doxygen prend en charge XML, commentaires) de plus, vous avez la possibilité de générer des documents dans un format connu pour .NET développeurs (avec des Châteaux et Châteaux de sable Aider FileBuilder).

Ah, et aussi essayer de GhostDoc...

Answer 2

Il ya plusieurs options pour la documentation:

• La gratuit de Microsoft. Utilisation DocXml les commentaires de la documentation, puis de Châteaux de sable ou un outil similaire pour construire MSDN style de la documentation. L'avantage, c'est que Visual Studio reconnaît la documentation (il la syntaxe des couleurs les commentaires), et la documentation est immédiatement capté par le système Intellisense (donc si vous passez le pointeur de votre souris sur une méthode que vous appelez, l'info-bulle affiche le résumé et les informations de paramètre que vous avez entré dans la Doc Commentaire)

• La libre Doxygen système. C'est plus facile à utiliser et plus souple, mais pas pris en charge par Visual Studio, donc vous perdez l'intellisense de la syntaxe et de la coloration des avantages. Sur le côté positif, Doxygen n'analyser le DocXml format, de sorte que vous pouvez obtenir le meilleur des deux mondes à l'aide de la DocXml format Doxygen pour générer de l'aide extérieure.

• Des produits commerciaux comme les DocumentX, qui vous permettent de modifier la documentation en WYSIWYG fenêtre.

Je recommande de commencer avec DocXml commentaires et Doxygen pour générer de l'aide extérieure, comme c'est le moins cher et le plus facile pour commencer, et conserve toutes les meilleures fonctionnalités de VIsual Studio (intellisense etc).

Je voudrais aussi vous suggère de regarder à mon complément, Atomineer Pro de la Documentation, qui permet la génération et la mise à jour de DocXml, Doxygen, Qt ou JavaDoc commentaires de format beaucoup plus rapide et plus facile au sein de VS - un complément idéal à la fois Doxygen et de Châteaux de sable.

Answer 3

Doxygen peut consommer C# doc commentaires (///) très bien. Documenter votre code comme normal et exécuter doxygen pour les analyser en autonome, html, chm et pdf fichiers. C'est de loin le plus polyvalent, simple et non-invasive.

Alors que doxygen n'est pas intégré à visual studio, il est livré avec un simple IDE et peuvent script trivialement comme une coutume outil externe. Personnellement, j'ai intégré doxygen dans mes scripts de compilation et il fonctionne parfaitement.

Enfin, doxygen est multi-plateforme (ce qui est un avantage si jamais vous trouvez un besoin de port Mono) et est nettement plus rapide que de Châteaux de sable (à la fois pour le programme d'installation et de fonctionnement).

Ceci est un exemple de doxygen de sortie pour le code C# sur un ~1Mloc projet: http://www.opentk.com/files/doc/annotated.html

Answer 4

.NET développeurs sont utilisés pour MSDN-comme la documentation du format utilisé dans VS aider. De préférence, directement intégré dans VS aider, car il donne certains bonus comme les F1 de l'aide, des filtres, des unifiée de l'Index et de table des matières. Plusieurs outils ont déjà été mentionnés. Je voudrais ajouter une plus commerciale, solution en un clic, VSdocman.

Commentaires de document XML sont grands parce qu'ils sont automatiquement utilisés également dans IntelliSense et Objet Navigateur Rapide Info.

Answer 5

Visual Studio ne dispose pas d'un système intégré de documentation.

Si vous voulez rester cohérent avec les autres langues, vous pouvez essayer d'utiliser Doxygen avec le Doxycomment Addin pour Visual Studio.

Pour le C# ou .NET de la documentation, plusieurs outils existent et les plus utilisés (à ma connaissance) est un château de sable.

Enfin, vous pouvez cocher cette entrée de blog qui fournit un petit script Python qui convertit en C# balises spécifiques dans Doxygen ceux.