Come fare riferimento a classi e metodi generici nella documentazione xml


198

Quando si scrive documentazione XML è possibile utilizzare <see cref="something">something</see>, che funziona ovviamente. Ma come si fa a fare riferimento a una classe o un metodo con tipi generici?

public class FancyClass<T>
{
  public string FancyMethod<K>(T value) { return "something fancy"; }
}

Se avessi scritto la documentazione XML da qualche parte, come avrei fatto riferimento alla classe di fantasia? come posso fare riferimento a FancyClass<string>? E il metodo?

Ad esempio, in una classe diversa, volevo far sapere all'utente che restituirò un'istanza di FancyClass<int>. Come potrei fare una cosa da vedere per questo?

Risposte:


257

Per fare riferimento al metodo:

/// <see cref="FancyClass{T}.FancyMethod{K}(T)"/> for more information.

3
Grazie per la risposta! In realtà manca la pagina di MSDN su <vedere>: msdn.microsoft.com/en-us/library/acd0tfbe.aspx
joce

6
In realtà credo che funzioni anche nelle descrizioni dei comandi VS2010, è necessario indicare il numero di argomenti generici, ad esempio "FancyClass 1{T}.FancyMethod1 {K} (T)"
Stephen Drew,

Non sono sicuro di cosa intendi a riguardo. Non ho mai dovuto aggiungere quelli, e ha sempre funzionato per me. Hai un esempio specifico in cui non funziona? In tal caso, si prega di pubblicarlo da qualche parte (o anche fornire una risposta da soli.)
Lasse V. Karlsen,

@Lasse, vedi la risposta di Steve e i commenti qui sotto. La tua risposta non copre i suggerimenti Intellisense corretti.
Jakub Januszkiewicz,

43
/// <summary>Uses a <see cref="FancyClass{T}" /> instance.</summary>

A proposito, era presente nella documentazione MSDN di .Net Framework 2.0 e 3.0 , ma è scomparso nella versione 3.5


4
che dire di un'istanza specifica di T? come una stringa? Forse non è possibile?
Svish,

cosa intendi? Non puoi dichiarare una versione specifica, quindi non puoi nemmeno farvi riferimento.
Lasse V. Karlsen,

Se ad esempio un metodo restituisce, ad esempio, solo List <stringa>. Ma non è importante :)
Svish,

7
Sì, mi stavo chiedendo anche ... resharpers scricchiola quando si scrive FancyClass {stringa} ma non quando si scrive FancyClass {String} ...
thinkbeforecoding

6
Il motivo dell'osservazione di cui sopra di "Think Before Coding" è che non funziona con gli alias c #. Ad esempio, è necessario utilizzare Int32invece di int, Singleanziché floatecc. (Inserire queste informazioni nel caso in cui qualcun altro si
imbatti

27

TL; DR:

"Come farei riferimento FancyClass<T>?"

   /// <see cref="FancyClass{T}"/>

"Che dire FancyClass<T>.FancyMethod<K>(T value)?"

   /// <see cref="FancyClass{T}.FancyMethod{K}(T)"/>

"Come posso fare riferimento a un FancyClass<string>?"

   /// <see cref="SomeType.SomeMethod(FancyClass{string})"/>
   /// <see cref="FancyClass{T}"/> whose generic type argument is <see cref="string"/>

Sebbene sia possibile fare riferimento a un metodo la cui firma include FancyClass<string>(ad esempio come tipo di parametro), non è possibile fare riferimento direttamente a un tipo generico chiuso. Il secondo esempio aggira questa limitazione. (Questo si vede ad esempio sulla pagina di riferimento MSDN per il System.String.Concat(IEnumerable<string>)metodo statico ). :

crefRegole per i commenti sulla documentazione XML :

  • Circondare l'elenco dei parametri di tipo generico con parentesi graffe{} anziché con <>parentesi angolari. Questo ti evita di sfuggire a quest'ultimo in quanto &lt;e &gt;- ricorda, i commenti della documentazione sono XML!

  • Se si include un prefisso (comeT: per i tipi, M:per i metodi, P:per le proprietà, F:per i campi), il compilatore non eseguirà alcuna convalida del riferimento, ma semplicemente copierà il crefvalore dell'attributo direttamente nell'output XML della documentazione. Per questo motivo, dovrai utilizzare la sintassi speciale "stringa ID" che si applica a tali file: usa sempre identificatori completi e usa i backtick per fare riferimento a parametri di tipo generico ( `nsu tipi,``n sui metodi).

  • Se si omette il prefisso , si applicano le normali regole di denominazione della lingua: è possibile eliminare gli spazi dei nomi per i quali è presente usingun'istruzione e utilizzare le parole chiave del tipo di lingua come intinvece di System.Int32. Inoltre, il compilatore verificherà la correttezza del riferimento.

crefFoglio informativo sui commenti alla documentazione XML :

namespace X
{
    using System;

    /// <see cref="I1"/>  (or <see cref="X.I1"/> from outside X)
    /// <see cref="T:X.I1"/>
    interface I1
    {
        /// <see cref="I1.M1(int)"/>  (or <see cref="M1(int)"/> from inside I1)
        /// <see cref="M:X.I1.M1(System.Int32)"/>
        void M1(int p);

        /// <see cref="I1.M2{U}(U)"/>
        /// <see cref="M:X.I1.M2``1(``0)"/>
        void M2<U>(U p);

        /// <see cref="I1.M3(Action{string})"/>
        /// <see cref="M:X.I1.M3(System.Action{System.String})"/>
        void M3(Action<string> p);
    }

    /// <see cref="I2{T}"/>
    /// <see cref="T:X.I2`1"/>
    interface I2<T>
    {
        /// <see cref="I2{T}.M1(int)"/>
        /// <see cref="M:X.I2`1.M1(System.Int32)"/>
        void M1(int p);

        /// <see cref="I2{T}.M2(T)"/>
        /// <see cref="M:X.I2`1.M2(`0)"/>
        void M2(T p);

        /// <see cref="I2{T}.M3{U}(U)"/>
        /// <see cref="M:X.I2`1.M3``1(``0)"/>
        void M3<U>(U p);
    }
}

Come fare riferimento solo alla Tparte?
nawfal,

4
<typeparamref name="T"/>
Capito

21

Nessuna delle risposte mostrate finora funziona completamente per me. ReSharper non converte il tag see in un Ctrlcollegamento + clic (ad esimmagine qui ) a meno che non si risolva completamente.

Se il metodo nell'OP fosse in uno spazio dei nomi chiamato Test, il collegamento completamente risolto al metodo mostrato sarebbe:

<see cref="M:Test.FancyClass`1.FancyMethod``1(`0)"/>

Poiché potresti essere in grado di allenarti, dovrebbe esserci solo un backtick prima del numero di parametri del tipo di classe, quindi due backtick prima del numero di parametri del tipo di metodo, quindi i parametri sono il parametro a indice zero con il numero appropriato di backtick.

Quindi possiamo vedere che FancyClassha un parametro di tipo di classe,FancyMethod ha un parametro di tipo e un oggetto diFancyClass tipo di parametro verrà passato al metodo.

Come puoi vedere più chiaramente in questo esempio:

namespace Test
{
    public class FancyClass<A, B>
    {
        public void FancyMethod<C, D, E>(A a, B b, C c, D d, E e) { }
    }
}

Il link diventa:

M:Test.FancyClass`2.FancyMethod``3(`0,`1,``0,``1,``2)

O "Class con due parametri di tipo che ha un metodo con tre parametri di tipo in cui i parametri del metodo sono ClassType1, ClassType2, MethodType1, MethodType2,MethodType3 "


Come nota aggiuntiva, non l'ho trovato documentato da nessuna parte e non sono un genio, il compilatore mi ha detto tutto questo. Tutto quello che devi fare è creare un progetto di test, abilitare la documentazione XML , quindi inserire il codice per cui vuoi elaborare un collegamento e inserire un commento doc XML su di esso ( ///):

namespace Test
{
    public class FancyClass<T>
    {
        ///
        public string FancyMethod<K>(T value) { return "something fancy"; }
    }

    public class Test
    {
        public static void Main(string[] args) { }
    }
}

Quindi crea il tuo progetto e la documentazione XML prodotta include il collegamento nell'elemento doc-> members-> membersotto l'attributo name:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Test</name>
    </assembly>
    <members>
        <member name="M:Test.FancyClass`1.FancyMethod``1(`0)">

        </member>
    </members>
</doc>

3
Questo dovrebbe ottenere più voti, soprattutto a causa del trucco per trovare la notazione corretta, senza dover passare attraverso prove ed errori. Complimenti amico mio
Peter,

10

Più lontano dalle risposte di Lasse e TBC:

/// <see cref="T:FancyClass`1{T}"/> for more information.

/// <see cref="M:FancyClass`1{T}.FancyMethod`1{K}(T)"/> for more information.

fornirà anche i suggerimenti corretti, mentre la loro versione lo rende con le parentesi graffe.


2
Usando <see cref = "System.Collections.Generic.List 1{T}"/>** causes a build-time warning: **XML comment on 'Blah' has syntactically incorrect cref attribute 'System.Collections.Generic.List1 <T> - ti andrebbe di approfondire come si dovrebbe usare questo?
Jakub Januszkiewicz

2
Ciao Jakub, Questo in effetti non sembra funzionare. L'unico modo in cui posso anche far funzionare correttamente i tooltip è <see cref = "T: <fullTypeName>` 1 {T} "/>.
Stephen Drew,

2
OK, ho parzialmente capito. Se il metodo stesso non è generico (come in Elenco <T> .Add ()), funziona: <vedi cref = "M: System.Collections.Generic.List`1 {T} .Add (T)" /> .
Jakub Januszkiewicz,

1
Non sembra funzionare per me. Ho <see cref = "M: System.Collections.Generic.List`1 {T}" /> nell'intestazione del commento per un metodo di estensione generico che ho scritto (converte un ArrayList in un Elenco <T>) ma ReSharper lo contrassegna come un errore di sintassi e IntelliSense lo mostra semplicemente alla lettera. VS 2010 / R # 6.1.37.86
Mike Loux,

8
Aha! Sono stato in grado di far funzionare <see cref = "T: System.Collections.Generic.List`1" /> " . Quindi, usare T: invece delle parentesi graffe ha funzionato. Espande l'intero spazio dei nomi, e il trucco non funziona se non includi lo spazio dei nomi, quindi non è perfetto, ma lo farà.
Mike Loux,

5
/// Here we discuss the use of <typeparamref name="TYourExcellentType"/>.
/// <typeparam name="TYourExcellentType">Your exellent documentation</typeparam>

3
Nota che le altre risposte coprono come fare riferimento a una classe generica, questa risposta ti mostra come fare riferimento al parametro type da solo, che era quello che stavo cercando di fare.
jrh

1
/// <see cref="FancyClass&lt;T>.FancyMethod&lt;K>(T)"/> for more information.
Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.