Documentazione del codice di libreria C++/CLI per l'uso da C# - i migliori strumenti e pratiche?

Question

Sto lavorando a un progetto in cui una libreria C++/cli viene utilizzata principalmente da un'applicazione C#.

C'è un modo per rendere i commenti del codice in C++/cli visibili a C# intellisence all'interno di visual studio?

Supponendo che non ci sia, quale sarebbe il modo migliore per documentare il codice C++/cli per renderlo più facile da usare da C# (e all'interno di C++/cli ovviamente)? Qual è la tua opinione sui commenti XML vs doxygen vs altri strumenti (quali)?

Answer 1

ho ottenuto di lavorare come segue:

1. Utilizzare commenti di stile XML per le voci di intestazione C++/CLI. Ciò significa che è richiesto il commento XML completo (tag triple-slash, tag <summary>)

2. Assicurarsi che l'opzione del compilatore C++ Generate XML Documentation Files sia attiva. Ciò dovrebbe generare un file XML con la documentazione con lo stesso nome dell'assembly (MyDll.xml).

3. Assicurarsi che il progetto C# faccia riferimento all'assembly MyDll.dll in cui MyDll.xml è presente anche nella stessa cartella. Quando si passa il mouse su un riferimento dall'assieme, MS Visual Studio caricherà la documentazione.

Questo ha funzionato per me in Visual Studio 2008 su un assembly creato per .NET 3.5.

Answer 2

Interessante. Dopo aver provato diversi metodi, sembra che l'intellisense tra un progetto C++ gestito e C# non funzioni.

L'esempio seguente vi darà adeguata IntelliSense in ambiente C++ in cui viene dichiarata, ma fa riferimento l'oggetto in C# non mostra nulla:

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

commenti XML non funzionano neanche. Direi che questo è un bug o richiede qualcosa che non riesco a capire. A giudicare dalla mancanza di risposte su questa domanda, forse un bug.

Per quanto riguarda la generazione di documentazione, suggerirei di seguire il percorso della documentazione XML. Doxygen supports reading XML documentation che è per lo più identico alla documentazione XML standard per C#. Lo fa tendono ad aggiungere linee in più solo per le aperture e chiusure di tag, ma è molto più leggibile rispetto a mio parere la seguente 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

Hai ragione. Non funziona. Il build C++ aggiungerà le informazioni di IntelliSense nel file master .ncb e otterrai il completamento automatico dei nomi dei metodi, ecc. Tuttavia, sei corretto nel senso che non sarai in grado di ottenere la descrizione "commento" su ogni metodo, ecc.

Answer 4

Probabilmente avrete un sacco di valore dando un'occhiata a Doxygen. E poi cercare Doxygen.NET - che è qualcosa che abbiamo scritto per il nostro uso che costruisce "Object Gerarchie" dalle uscite di file XML da Doxygen ...

Answer 5

DocXml ha il vantaggio principale di essere supportato da VS (colorazione della sintassi, intellisense, esportazione automatica nei file XML). Gli strumenti Doxygen possono leggere il formato DocXml in modo da poterli comunque utilizzare anche con questo formato.

Per aiutarti a generare commenti di testo accurati e accurati con il minimo sforzo, ti consigliamo di controllare il mio addin AtomineerUtils. Questa operazione richiede la maggior parte del lavoro di creazione e aggiornamento di commenti in formato DocXml, Doxygen, JavaDoc o Qt e supporta C, C++, C++/CLI, C#, Java, JavaScript, TypeScript, JScript, UnrealScript, PHP e Visual Basic.