Documentación del código de la biblioteca C++/CLI para usar desde C# - ¿las mejores herramientas y prácticas?

Question

Estoy trabajando en un proyecto donde una biblioteca C++/cli se usa principalmente desde una aplicación C#.

¿Hay alguna manera de hacer que los comentarios del código en C++/cli sean visibles para C# intellisence dentro de Visual Studio?

Suponiendo que no exista, ¿cuál sería la mejor manera de documentar el código C++/cli para permitir su uso más fácil desde C# (y dentro de C++/cli por supuesto)? ¿Cuál es su opinión sobre los comentarios XML vs doxygen vs otras herramientas (que)?

Answer 1

he conseguido hacerlo funcionar de la siguiente manera:

1. Utilice los comentarios de estilo XML para sus entradas de encabezado C++/CLI. Esto significa que se requiere el comentario XML completo (comentarios de triple barra, <summary> etiqueta como mínimo)

2. Asegúrese de que la opción Generate XML Documentation Files del compilador de C++ esté activada. Esto debería generar un archivo XML con documentación con el mismo nombre que su ensamblaje (MyDll.xml).

3. Asegúrese de que el proyecto C# hace referencia a su ensamblado MyDll.dll donde MyDll.xml también está presente en la misma carpeta. Cuando pasa el mouse sobre una referencia del ensamblaje, MS Visual Studio cargará la documentación.

Esto funcionó para mí en Visual Studio 2008 en un ensamblado creado para .NET 3.5.

Answer 2

Interesante. Después de probar varios métodos, se parece al intellisense entre un proyecto de C++ administrado y C# no funciona.

El siguiente ejemplo le dará intelisense adecuada en el entorno C++ donde se declara, pero hace referencia al objeto en C# no muestra nada:

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

comentarios XML no funcionan bien. Supongo que esto es un error o requiere algo que no puedo entender. A juzgar por la falta de respuestas sobre esta pregunta, quizás un error.

En cuanto a la generación de documentación, recomiendo seguir la ruta de la documentación XML. Doxygen supports reading XML documentation, que es en su mayoría idéntico a la documentación XML estándar para C#. Se tiende a añadir líneas adicionales sólo para las aberturas y cierres de etiqueta, pero es mucho más fácil de leer en mi opinión, que la siguiente alternativa doxygen:

//! 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() 
*/ 

Answer 3

Tiene usted razón. No funciona La compilación C++ agregará su información IntelliSense en el archivo maestro .ncb, y obtendrá la autocompletación de los nombres de los métodos, etc. Sin embargo, tiene razón en que no podrá obtener la descripción de "comentario" sobre cada método, etc.

Answer 4

Probablemente tengas mucho valor al echarle un vistazo a Doxygen. Y luego mirar hacia arriba Doxygen.NET - que es algo que escribimos para nuestro propio uso que se basa "Object jerarquías" de las salidas de archivos XML desde Doxygen ...

Answer 5

DocXml tiene la gran ventaja de ser compatible con VS (coloreado de sintaxis, intellisense, exportación automática a los archivos XML). Las herramientas de Doxygen pueden leer el formato DocXml para que pueda usarlas también con este formato.

Para ayudarlo a generar comentarios de Doc ordenados y precisos con un mínimo de esfuerzo, le recomendamos que consulte mi complemento AtomineerUtils. Esto elimina la mayor parte del trabajo de crear y actualizar los comentarios DocXml, Doxygen, JavaDoc o Qt, y es compatible con los códigos C, C++, C++/CLI, C#, Java, JavaScript, TypeScript, JScript, UnrealScript, PHP y Visual Basic.