2009-06-24 9 views
43

Je travaille sur un projet où une bibliothèque C++/cli est principalement utilisée à partir d'une application C#.Documenter le code de bibliothèque C++/CLI à utiliser à partir des meilleurs outils et pratiques C#?

Est-il possible de faire les commentaires du code en C++/cli visible C# intellisence au sein du studio visuel? En supposant qu'il n'y en ait pas, quelle serait la meilleure façon de documenter le code C++/cli pour permettre son utilisation plus facile de C# (et dans C++/cli bien sûr)? Quelle est votre opinion sur les commentaires XML vs doxygen vs autres outils (qui)?

Répondre

48

J'ai eu à travailler comme suit:

  1. commentaires de style XML pour utiliser vos entrées d'en-tête C++/CLI. Cela signifie que le commentaire XML complet est requis (commentaires à triple barre oblique, <summary> au minimum)

  2. Assurez-vous que l'option du compilateur C++ Generate XML Documentation Files est activée. Cela devrait générer un fichier XML avec une documentation portant le même nom que votre assembly (MyDll.xml).

  3. Assurez-vous que le projet C# référence votre assembly MyDll.dll où MyDll.xml est également présent dans le même dossier. Lorsque vous passez la souris sur une référence de l'assembly, MS Visual Studio chargera la documentation.

Cela a fonctionné pour moi dans Visual Studio 2008 sur un assembly construit pour .NET 3.5.

+0

Ouais, l'astuce consiste à copier le XML (et aussi PDB si vous voulez déboguer) à côté de la DLL que vous référencez. Cela fonctionnera aussi dans VS2005. –

+3

Fonctionne également dans Visual Studio 2010. La seule différence est que les fichiers xml ont l'extension ".xdc" – user502144

+0

Beaucoup de upvotes sur ce sujet - Suivi de votre recommandation (fichier confirmé xml' est présent et les commentaires existent, mais intellisense n'affiche pas de commentaires.Ceci est dans VS2017. –

2

Intéressant. Après avoir essayé plusieurs méthodes, il semble que l'intellisense entre un projet C++ géré et C# ne fonctionne pas.

L'exemple suivant vous donnera IntelliSense appropriée dans l'environnement C++ où elle est déclarée, mais faisant référence l'objet en C# montre rien:

// Gets the value of my ID for the object, which is always 14. 
public: virtual property int MyId 
{ 
    int get() { return 14; } 
} 

commentaires XML ne fonctionnent pas non plus. Je suppose que c'est soit un bug, ou nécessite quelque chose que je ne peux pas comprendre. A en juger par le manque de réponses à cette question, peut-être un bug.

En ce qui concerne la génération de documents, je vous conseille d'aller le chemin de la documentation XML. Doxygen supports reading XML documentation qui est essentiellement identique à la documentation XML standard pour C#. Il a tendance à ajouter des lignes supplémentaires juste pour les ouvertures d'étiquette et de fermeture, mais il est beaucoup plus facile à lire, à mon avis que l'alternative doxygen suivante:

//! A normal member taking two arguments and returning an integer value. 
/*! 
    \param a an integer argument. 
    \param s a constant character pointer. 
    \return The test results 
    \sa Test(), ~Test(), testMeToo() and publicVar() 
*/ 
0

Vous avez raison. Ça ne marche pas. La construction C++ ajoutera ses informations IntelliSense dans le fichier maître .ncb, et vous obtiendrez l'auto-complétion des noms de méthodes, etc. Cependant, vous avez raison de ne pas pouvoir obtenir la description "comment" de chaque méthode, etc. .

0

Vous aurez probablement beaucoup de valeur jeter un oeil à Doxygen. Et puis regarder Doxygen.NET - qui est quelque chose que nous avons écrit pour notre propre usage qui construit « Object Hiérarchies » à partir des sorties de fichiers XML à partir Doxygen ...

2

DocXml a l'avantage majeur d'être pris en charge par VS (de coloration syntaxique, IntelliSense, l'exportation automatique des fichiers XML). Les outils Doxygen peuvent lire le format DocXml afin que vous puissiez toujours les utiliser avec ce format.

Pour vous aider à générer des commentaires Doc propres et précis avec un minimum d'effort, vous voudrez peut-être vérifier mon addin AtomineerUtils. Cela prend la majeure partie du travail de création et de mise à jour des commentaires DocXml, Doxygen, JavaDoc ou Qt, et il prend en charge C, C++, C++/CLI, C#, Java, JavaScript, TypeScript, JScript, UnrealScript, PHP et Visual Basic.

Questions connexes