Modi per sincronizzare l'interfaccia e i commenti di implementazione in C # [chiuso]

Esistono modi automatici per sincronizzare i commenti tra un'interfaccia e la sua implementazione? Attualmente li sto documentando entrambi e non vorrei tenerli sincronizzati manualmente.

AGGIORNARE:

Considera questo codice:

interface IFoo{
    /// <summary>
    /// Commenting DoThis method
    /// </summary>
    void DoThis();
}
class Foo : IFoo {
    public void DoThis();
}

Quando creo una classe come questa:

IFoo foo=new Foo();
foo.DoThis();//comments are shown in intellisense

Qui i commenti non vengono visualizzati:

Foo foo=new Foo();
foo.DoThis();//comments are not shown in intellisense

Il <inheritDoc/>tag genererà perfettamente la documentazione in Sand Castle, ma non funziona nei tooltip di intellisense.

Per favore condividi le tue idee.

Grazie.

Puoi farlo abbastanza facilmente usando il inheritdoctag Microsoft Sandcastle (o NDoc) . Non è ufficialmente supportato dalle specifiche, ma i tag personalizzati sono perfettamente accettabili, e infatti Microsoft ha scelto di copiare questo (e uno o due altri tag) da NDoc quando ha creato Sandcastle.

/// <inheritdoc/>
/// <remarks>
/// You can still specify all the normal XML tags here, and they will
/// overwrite inherited ones accordingly.
/// </remarks>
public void MethodImplementingInterfaceMethod(string foo, int bar)
{
    //
}

Ecco la pagina della guida dalla GUI di Sandcastle Help File Builder, che ne descrive completamente l'utilizzo.

(Ovviamente, questa non è specificamente "sincronizzazione", come menziona la tua domanda, ma sembrerebbe comunque essere esattamente quello che stai cercando.)

Come nota, questa suona come un'idea perfettamente giusta per me, anche se ho notato che alcune persone pensano che dovresti sempre rispettare i commenti nelle classi derivate e implementate. (In realtà l'ho fatto io stesso documentando una delle mie librerie e non ho riscontrato alcun problema.) Non c'è quasi sempre alcun motivo per cui i commenti differiscano, quindi perché non ereditare e farlo nel modo più semplice?

Modifica: per quanto riguarda il tuo aggiornamento, Sandcastle può anche occuparsene per te. Sandcastle può generare una versione modificata del file XML effettivo che utilizza per l'input, il che significa che puoi distribuire questa versione modificata insieme alla DLL della tua libreria invece di quella creata direttamente da Visual Studio, il che significa che hai i commenti in intellisense e il file di documentazione (CHM, qualunque sia).

Se non lo stai già utilizzando, ti consiglio vivamente un addon gratuito di Visual Studio chiamato GhostDoc . Facilita il processo di documentazione. Dai un'occhiata al mio commento su una domanda in qualche modo correlata.

Sebbene GhostDoc non eseguirà la sincronizzazione automaticamente, può aiutarti con il seguente scenario:

Hai un metodo di interfaccia documentato. Implementa questa interfaccia in una classe, premi il tasto di scelta rapida GhostDoc Ctrl-Shift-De il commento XML dell'interfaccia verrà aggiunto al metodo implementato.

Vai su Opzioni -> Impostazioni tastiera e assegna un tasto a GhostDoc.AddIn.RebuildDocumentation(Ho usato Ctrl-Shift-Alt-D).

Ora, se modifichi il commento XML sull'interfaccia , premi semplicemente questo tasto di scelta rapida sul metodo implementato e la documentazione verrà aggiornata. Sfortunatamente, questo non funziona viceversa.

Di solito scrivo commenti come questo:

/// <summary>
/// Implements <see cref="IMyInterface.Foo(string, int)"/>
/// </summary>
/// <returns></returns>

I metodi sono utilizzati solo dall'interfaccia, quindi questo commento non viene nemmeno mostrato nei suggerimenti durante la codifica.

Modificare:

Se vuoi vedere i documenti quando chiami direttamente la classe e non usi l'interfaccia, devi scriverli due volte o usare uno strumento come GhostDoc.

Prova GhostDoc ! Per me funziona :-)

Modifica: ora che sono stato informato del supporto di Sandcastle, appoggio <inheritdoc/>il post di Noldorin. È una soluzione molto migliore. Tuttavia, consiglio ancora GhostDoc su base generale.

Ho una risposta migliore: FiXml ., Sono uno dei suoi autori

La clonazione dell'approccio è sicuramente funzionante, ma presenta svantaggi significativi, ad esempio:

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

Come è stato accennato, c'è un <inheritdoc>tag in Sandcastle , ma ha pochi svantaggi rispetto a FiXml:

• Sandcastle produce file di help HTML compilati - normalmente non modifica .xmlfile contenenti commenti XML estratti (alla fine, questo non può essere fatto "al volo" durante la compilazione).
• L'implementazione di Sandcastle è meno potente. Ad esempio, è no <see ... copy="true" />.

Vedere la <inheritdoc>descrizione di Sandcastle per ulteriori dettagli.

Breve descrizione di FiXml: è un post-processore di documentazione XML prodotto da C # \ Visual Basic .Net. È implementato come attività MSBuild, quindi è abbastanza facile integrarlo in qualsiasi progetto. Risolve alcuni casi fastidiosi relativi alla scrittura di documentazione XML in questi linguaggi:

• Nessun supporto per ereditare la documentazione dalla classe base o dall'interfaccia. Cioè una documentazione per ogni membro sovrascritto dovrebbe essere scritta da zero, sebbene normalmente sia abbastanza desiderabile ereditarne almeno una parte.
• Nessun supporto per l'inserimento di modelli di documentazione di uso comune , come "Questo tipo è singleton - usa la sua <see cref="Instance" />proprietà per ottenerne l'unica istanza.", O anche "Inizializza una nuova istanza di <CurrentType>classe".

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

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

Ecco la sua pagina web e la pagina di download .

/// <inheritDoc/>

Leggi qui

Usa questo

Ho creato una libreria per post-elaborare i file di documentazione XML per aggiungere il supporto per il tag <inheritdoc />.

Sebbene non sia di aiuto con Intellisense nel codice sorgente, consente di includere i file di documentazione XML modificati in un pacchetto NuGet e quindi funziona con Intellisense nei pacchetti NuGet di riferimento.

Maggiori informazioni su www.inheritdoc.io (versione gratuita disponibile).

Non farlo. Pensala in questo modo: se entrambi i commenti devono essere sempre uguali, uno di essi non è necessario. Deve esserci una ragione per il commento (oltre a una sorta di strano obbligo di bloccare ogni funzione e variabile nel commento) quindi è necessario capire quale sia quella ragione unica e documentarla.

Con ReSharper puoi copiarlo, ma non credo che sia sempre sincronizzato.