XML Commenti sulla documentazione con interfacce e classe che implementa (es) [chiusa]

Question

sto documentando un assieme utilizzando Commenti , da cui un file chm verrà creata usando Sandcastle .

Il mio assieme contiene diverse interfacce, ciascuno dei quali è realizzato da una classe (nel mio scenario di questi sono servizi WCF).

Ho aggiunto la documentazione alle interfacce, non v'è alcun modo per me per documentare automaticamente i relativi metodi alle classi di attuazione?

Answer 1

Ci sembra non essere alcun supporto per tale autodocumentation in Sandcastle. Il Sandcastle Aiuto Builder File implementa anche un tag inheritdoc personalizzato.

Dal sito SHFB:

  

È incluso il supporto per il    tag che consente di   ereditare la documentazione dalla base   tipi / membri. Questo viene implementato tramite   uno strumento standalone quindi può anche essere   utilizzato da altri strumenti di terze parti e   costruire script. Questo strumento fornisce   funzioni oltre a quelle trovate nel   costruire componenti in dotazione   Sandcastle.

secondo aggiornamento: in base al questo elemento di lavoro , il "supporto" Sandcastle per inheritdoc è attraverso lo strumento SHFB. Linea di fondo suppongo sia, SHFB risolve il problema.

Answer 2

Ho una risposta migliore:. FIXML

commenti Clonazione con GhostDoc \ AtomineerUtils è certamente l'approccio al lavoro, ma ha svantaggi significativi, ad es .:

• Quando il commento originale viene modificato (il che accade spesso durante lo sviluppo), il suo clone non è.
• Si sta producendo enormi quantità di duplicati. Se si sta utilizzando qualsiasi codice sorgente strumenti di analisi (ad esempio Duplicate Finder in Team City), lo farà trovare principalmente i tuoi commenti.

Come è stato detto, non c'è tag <inheritdoc> in Sandcastle , ma ha alcuni svantaggi rispetto alle FIXML:

• Castello di sabbia produce file della Guida HTML compilato - non modifica i file .xml contenente commenti XML estratti. Ma questi file sono utilizzati da molti strumenti, tra cui .NET Reflector e il browser di classe \ IntelliSense in Visual Studio .NET. Quindi, se si utilizza solo Castello di sabbia, non si vedrà ereditato la documentazione lì.
• implementazione del Sandcastle è meno potente. Per esempio. il non è un <see ... copy="true" />.

<inheritdoc> descrizione di Sandcastle per ulteriori dettagli.

Breve descrizione FIXML: si tratta di un post-processor di documentazione XML prodotto da C # \ Visual Basic .Net. E 'implementato come compito MSBuild, quindi è abbastanza facile da integrare a qualsiasi progetto. Si rivolge pochi casi fastidiosi relativi alla documentazione scritta XML in queste lingue:

• Nessun supporto per ereditare la documentazione dalla classe base o interfaccia. Vale a dire una documentazione per qualsiasi membro override dovrebbe essere scritto da zero, anche se di solito è abbastanza desiderabile per ereditare almeno la parte di esso.
• Nessun supporto per l'inserimento di modelli di documentazione comunemente usati , come ad esempio “Questo tipo è Singleton -. Usare la sua proprietà <see cref="Instance" /> per ottenere l'unica istanza di esso”, o anche “inizializzare una nuova istanza di classe <CurrentType> “.

Per risolvere i problemi menzionati, sono previsti i seguenti tag XML aggiuntivi:

• tag <inheritdoc />, <inherited />
• attributo <see cref="..." copy="..." /> in tag <see/>.

Ecco sua pagina web e pagina di download .

Answer 3

Uno strumento come GhostDoc in grado di generare la documentazione sulle classi di attuazione, quando si usarlo di scorciatoia da tastiera. Questo non è del tutto automatica, ma potrebbe aiutare a prevenire troppa copia incolla.

Forse potrebbe essere automatizzato con uno script.

Answer 4

AtomineerUtils si auto-genera commenti per te, e raccoglie la documentazione da sovraccarichi e classe di base override esistente, risparmiando un sacco di problemi nel duplicare le informazioni in cui è necessario.

http://www.atomineer.com/AtomineerUtils.html