Generazione della documentazione del codice [chiusa]

Naviga le tue risposte
3

Voglio generare la documentazione del codice in un formato semplice. Gli elementi chiave sono Method Signature, membri, costruttori, metodi. Sto prendendo varie applicazioni in .NET e creando documentazione per loro. Aggiungerò note a ciascun articolo. Il risultato finale dovrebbe essere simile alla documentazione MSDN o API Java.

Quindi, voglio prendere il mio codice sorgente e avere una sorta di modello generato a cui posso aggiungere note. Voglio scegliere e scegliere determinate classi e non altre attraverso varie applicazioni.

Non sto parlando di documentazione intellisense. Questa documentazione sarà usata come riferimento al di fuori dello studio visivo. AFAIK, questo è tutto ciò che i commenti XML fanno bene in .NET.

Sto documentando varie interfacce e punti di ingresso per la scrittura di estensioni per un'applicazione di terze parti. Non possediamo il loro codice, quindi non posso entrare e aggiungere commenti XML alle loro interfacce, classi, ecc. Invece, ho bisogno di implementare l'interfaccia e commentarla. Quindi documentalo sul web. Documentare ogni implementazione solo per spiegare la loro architettura è ridondante. Non documentano le loro cose ... questo è il problema principale qui.

C'è qualche strumento che può aiutare con questo processo? Cosa suggerisci?

    
posta P.Brian.Mackey 27.02.2012 - 16:56
fonte

3 risposte

5

Doxygen è molto utile per tradurre XML in un formato leggibile dall'uomo, come la Guida HTML o HTML in stile MSDN. (chm) Funzionerà sia con XML generato da Visual Studio, sia con XML creato da te o acquisito da altre fonti.

Un'altra opzione è Sandcastle e SCHFP , anche se ha visto meno manutenzione.

In entrambi i casi, è possibile estendere il markup XML per più di VS Intellisense, inclusi i commenti che devono essere utilizzati solo per la documentazione esterna, ecc.

    
risposta data 27.02.2012 - 19:50
fonte
2

Questo è incorporato in .Net usando la seguente sintassi 

/// <summary>
///  This class performs an important function.
/// </summary>
public class MyClass{}

e quindi utilizzare un progetto di codeplex chiamato SandCastle

Sandcastle produce una documentazione completa, in stile MSDN, riflettendo sugli assembly di origine e opzionalmente integrando i commenti della documentazione XML.

Commenti XML su MSDN: link

SandCastle: link

    
risposta data 28.02.2012 - 01:27
fonte
1

Uso NaturalDocs . Il vantaggio (e presumo il nome) deriva dal fatto che deduce la formattazione principalmente dalla spaziatura, e non dai tag. Non devi decorare i tuoi commenti con un sacco di <method> e cose del genere, rendendo i commenti molto più leggibili "in the wild".

Un commento di NaturalDocs sarebbe simile a: 

/* Function:  my_method
 * 
 * Accepts a Turing machine and an infinite data tape, and determines
 * whether it will halt.
 *
 * Parameters:
 *   turing_id - The ID of a valid Turing machine.
 *   tape_ptr  - A pointer to the start of the inifite-length tape.
 *
 * Returns:
 *   If the machine halts, returns 0.  If the machine doesn't halt,
 *   return value is undefined.
 */
extern int my_method(turing_id_t turing_id, void *tape_ptr);

NaturalDocs prenderà ciò e genererà un file HTML con una firma appropriata, una descrizione del metodo, un elenco di parametri formattati in tabella e qualsiasi sezione aggiuntiva ( Returns qui). Genererà inoltre un sommario che si imposterà in modo predefinito sull'organizzazione per file. Puoi anche raggruppare le cose per tipi diversi da Function (come Types , Macros e così via).

Potrei sembrare troppo entusiasta, ma quando ci siamo spostati su NaturalDocs abbiamo buttato fuori dalle nostre testate una grande quantità di piastre e le abbiamo fatte sembrare molto di più ... (tosse) ... naturale.

    
risposta data 27.02.2012 - 23:07
fonte

Leggi altre domande sui tag

Quale keymap preferisci in ReSharper? Quando è opportuno sviluppare un'applicazione gui, al contrario di un'applicazione web?