documentation - variable - Documentar el código de la biblioteca C++/CLI para usar desde c#: ¿mejores herramientas y prácticas?

examples doxygen

Question

Estoy trabajando en un proyecto en el que se utiliza una biblioteca c ++ / cli principalmente de la aplicación ac #.

¿Hay alguna forma de hacer que los comentarios de código en c ++ / cli sean visibles para la inteligencia # # dentro de Visual Studio?

Suponiendo que no lo haya, ¿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, por supuesto, dentro de c ++ / cli)? ¿Cuál es su opinión sobre los comentarios XML frente a doxygen frente a otras herramientas (cuáles)?

Answer 1

DocXml tiene la gran ventaja de ser compatible con VS (color de sintaxis, inteligencia, exportación automática a los archivos XML). Las herramientas de Doxygen pueden leer el formato DocXml, por lo que aún puede usarlas con este formato también.

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

Answer 2

Interesante. Después de probar varios métodos, parece que la inteligencia entre un proyecto de C ++ administrado y C # no funciona.

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

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

Los comentarios XML tampoco funcionan. Supongo que esto es un error o requiere algo que no puedo entender. A juzgar por la falta de respuestas a esta pregunta, tal vez un error.

En cuanto a la generación de documentación, recomiendo ir por la ruta de la documentación XML. Doxygen admite la lectura de documentación XML, que es en su mayoría idéntica a la documentación estándar XML para C #. Tiende a agregar líneas adicionales solo para las aperturas y cierres de etiquetas, pero en mi opinión es mucho más legible que la siguiente alternativa de 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

Lo he hecho funcionar de la siguiente manera:

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

2. Asegúrese de que la opción del compilador C ++ Generar archivos de documentación XML 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 # haga 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 me funcionó en Visual Studio 2008 en un ensamblado creado para .NET 3.5.

Answer 4

Probablemente tengas mucho valor echando un vistazo a Doxygen. Y luego busque Doxygen.NET, que es algo que escribimos para nuestro propio uso, que crea "jerarquías de objetos" a partir de los resultados del archivo XML de Doxygen ...

Answer 5

Tienes razón. No funciona La compilación de C ++ agregará su información de IntelliSense al archivo maestro .ncb, y obtendrá el autocompletado de los nombres de los métodos, etc. Sin embargo, es correcto que no podrá obtener la descripción de "comentarios" sobre cada método, etc. .