Documenti xml .NET - ereditarietà della documentazione

Question

NDoc ha un elemento XML inheritdoc che consente di ereditare la documentazione di un membro dalla classe padre (o un'interfaccia implementata). Tuttavia, Visual Studio (ovvero il compilatore C #) non comprende questo tag e si lamenta del fatto che la documentazione non sia presente o completa. Anche StyleCop e alcuni altri strumenti. Esiste un approccio alternativo? Come si fa a mantenere i documenti completi, ma senza duplicare le descrizioni XML?

Answer 1

Un'alternativa è usare GhostDoc - un componente aggiuntivo per Visual Studio che genera automaticamente commenti per te. Questo duplica ovviamente la descrizione XML, che fa parte di ciò che stai cercando di evitare, ma almeno lo fa automaticamente per te.

Cosa succede se si interrompono completamente i documenti per i metodi che vengono ereditati o i metodi di interfaccia di sostituzione? Ho il sospetto che dipenda da come hai configurato NDoc, ma certamente nella documentazione MSDN sembra ereditare naturalmente i documenti - e un rapido controllo suggerisce che VS non si innervosirà quando non produci documenti per un metodo ereditato. Vale la pena provare, certamente.

Answer 2

Ho una risposta migliore: FiXml .

La clonazione dei commenti con GhostDoc è certamente un approccio funzionante, ma presenta notevoli svantaggi, ad es .:

• Quando viene modificato il commento originale (che si verifica spesso durante lo sviluppo), il suo clone non lo è.
• Stai producendo enormi quantità di duplicati. Se ne stai usando uno qualsiasi strumenti di analisi del codice sorgente (ad es. Duplicate Finder in Team City), lo farà trova principalmente i tuoi commenti.

Breve descrizione di FiXml: è un post-processor della documentazione XML prodotta da C # \ Visual Basic .Net. È implementato come compito di MSBuild, quindi è abbastanza facile integrarlo in qualsiasi progetto. Risolve alcuni casi fastidiosi legati alla scrittura di documentazione XML in queste lingue:

• Nessun supporto per ereditare la documentazione dalla classe base o dall'interfaccia. I.e. una documentazione per qualsiasi membro sovrascritto dovrebbe essere scritta da zero, anche se normalmente è abbastanza desiderabile ereditarne almeno la parte.
• Nessun supporto per l'inserimento di modelli di documentazione comunemente usati , come & # 8220; Questo tipo è singleton: usa la sua proprietà <see cref="Instance" /> per ottenerne l'unica istanza. & # 8221 ;, o anche & # 8220; Inizializza una nuova istanza di <CurrentType> classe. & # 8221;

Per risolvere i problemi citati, vengono forniti i seguenti tag XML aggiuntivi:

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

Ecco la sua pagina web e pagina di download (collegamenti interrotti).

Infine, c'è <inheritdoc> tag in Sandcastle - è decisamente meglio usarlo che copiare i commenti XML, ma presenta alcuni svantaggi rispetto a FiXml:

• Sandcastle produce file di aiuto HTML compilati - non modifica .xml file contenente commenti XML estratti. Ma questi file sono usati da molti strumenti, incluso .NET Reflector e classe browser \ IntelliSense in Visual Studio .NET. Quindi, se usi solo Sandcastle, non vedrai la documentazione ereditata lì.
• L'implementazione di Sandcastle è meno potente. Per esempio. il no <see ... copy="true" />.

Vedi Sandcastle's <=> description per ulteriori dettagli.

Answer 3

Ho creato uno strumento da riga di comando per postelaborare i file di documentazione XML per aggiungere il supporto per < inheritdoc / > tag.

Non aiuta con Intellisense nel codice sorgente ma consente di includere i file di documentazione XML modificati in un pacchetto NuGet e quindi funziona con Intellisense nei pacchetti NuGet di riferimento.

Vedi www.inheritdoc.io per dettagli (versione gratuita disponibile).