Visual Studio avec DoxyGen pour la documentation, ou devrions-nous utiliser autre chose?
Nous utilisons actuellement DoxyGen pour documenter le code écrit en C/C++, PHP et Java. Pour avoir un environnement cohérent, il serait agréable de l'utiliser également pour la documentation C #.
Cependant, nous nous demandons:
- Voyez-vous des avantages dans la mise en page ou la structure de la documentation générée en utilisant autre chose que DoxyGen? Nous générons de la documentation pour les développeurs externes expérimentés avec C # et la plate-forme .NET. Peut-être sont-ils habitués à un certain format de documentation?
- Dans quelle mesure DoxyGen peut-il être intégré à Visual Studio? Y a-t-il quelque chose qui permet une génération en un clic de documentation à l'intérieur de l'EDI?
- Un autre système de documentation est-il plus intégré à Visual Studio?
La façon par défaut de documenter le code C # dans Visual Studio est de commentaires de documentation XML . À mon avis, c'est la meilleure façon de procéder pour le code C # car la prise en charge de celui-ci est déjà intégrée dans Visual Studio (complétion automatique des balises de commentaire, avertissement concernant les paramètres manquants ou mal orthographiés, ...). Pour documenter une méthode, tapez simplement trois barres obliques (///) devant le corps de la méthode, et Visual Studio insérera un modèle de commentaire vide à remplir, comme ceci:
/// <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 tous les commentaires, qui serait ensuite alimenté dans un générateur de documentation comme Sandcastle . 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 recommanderais d'utiliser des commentaires XML sur des commentaires Doxygen spéciaux pour le code C #. De cette façon, vous avez toutes les options. Vous pouvez générer de la documentation dans la mise en page Doxygen standard que votre organisation connaît (car Doxygen prend en charge les commentaires XML) et vous avez la possibilité de générer de la documentation dans un format connu des développeurs .NET (avec Sandcastle et Sandcastle Help FileBuilder =).
Ah, et essayez aussi GhostDoc ...
Il existe plusieurs options de documentation:
La manière Microsoft gratuite. Utilisez les commentaires de documentation DocXml, puis Sandcastle ou un outil similaire pour créer une documentation de style MSDN. L'avantage de ceci est que Visual Studio reconnaît la documentation (il colore la syntaxe des commentaires) et la documentation est instantanément récupérée par le système Intellisense (donc si vous passez le pointeur de votre souris sur une méthode que vous appelez, l'info-bulle affichera le informations de résumé et de paramètre que vous avez entrées dans le commentaire du document)
Le système Doxygen gratuit. Ceci est plus facile à utiliser et plus flexible, mais n'est pas pris en charge par Visual Studio, vous perdez donc les avantages de coloration d'intellisense et de syntaxe. Du côté positif, Doxygen analyse le format DocXml, vous pouvez donc tirer le meilleur parti des deux mondes en utilisant le format DocXml avec Doxygen pour générer l'aide externe.
Produits commerciaux comme DocumentX, qui vous permettent de modifier la documentation dans une fenêtre WYSIWYG.
Je recommanderais de commencer par les commentaires DocXml et Doxygen pour générer l'aide externe, car c'est la façon la moins chère et la plus simple de commencer, et conserve toutes les meilleures fonctionnalités de VIsual Studio (intellisense, etc.).
Je vous suggère également de consulter mon complément, Documentation Atomineer Pro , qui rend la génération et la mise à jour des commentaires au format DocXml, Doxygen, Qt ou JavaDoc beaucoup plus rapides et plus faciles dans VS - un complément idéal à la fois Doxygen et Sandcastle.
Doxygen peut très bien consommer les commentaires C # doc (///). Documentez votre code comme d'habitude et exécutez doxygen pour les numériser dans des fichiers html, chm et pdf autonomes. C'est de loin l'approche la plus polyvalente, simple et non invasive.
Bien que doxygen ne soit pas intégré dans Visual Studio, il est livré avec un simple IDE et peut être scripté trivialement comme un outil externe personnalisé. Personnellement, j'ai intégré doxygen dans mes scripts de construction et cela fonctionne parfaitement.
Enfin, doxygen est multiplateforme (ce qui est un avantage si jamais vous avez besoin de porter sur Mono) et est beaucoup plus rapide que SandCastle (à la fois pour la configuration et pour l'exécution).
Ceci est un exemple de sortie doxygen pour le code C # sur un projet ~ 1Mloc: http://www.opentk.com/files/doc/annotated.html
Les développeurs .NET sont habitués au format de documentation de type MSDN utilisé dans l'aide de VS. De préférence directement intégré dans l'aide VS car il offre des fonctionnalités bonus comme l'aide F1, les filtres, l'index unifié et la table des matières. Plusieurs outils ont déjà été mentionnés. J'ajouterais une solution commerciale en un seul clic, VSdocman .
Les commentaires sur les documents XML sont excellents car ils sont également utilisés automatiquement dans IntelliSense et Quick Info du navigateur d'objets.
Visual Studio ne dispose pas d'un système de documentation intégré.
Si vous souhaitez rester cohérent avec les autres langues, vous pouvez essayer d'utiliser Doxygen avec le Doxycomment Addin pour Visual Studio.
Pour la documentation C # ou .NET, plusieurs outils existent et le plus utilisé (à ma connaissance) est Sandcastle .
Enfin, vous pouvez vérifier cela entrée de blog qui fournit un petit script Python qui convertit certaines balises spécifiques à C # en balises Doxygen.