Come riferimento alle classi generiche e metodi di documentazione XML

Question

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

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

Se stavo per scrivere documentazione XML da qualche parte, come potrei fare riferimento alla classe di fantasia? come posso fare riferimento a un FancyClass<string>? Che dire del metodo?

Per esempio, in una classe diversa ho voluto lasciare all'utente di sapere che tornerò un'istanza di FancyClass<int>. Come potrei fare una cosa vedere cref per questo?

Answer 1

Per fare riferimento il metodo:

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

Answer 2

/// <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 spariscono nella versione 3.5

Answer 3

TL; DR:

  

"Come dovrei fare riferimento FancyClass<T>?"

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

  

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

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

  

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

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

Mentre possono riferimento a un metodo cui firma comprende FancyClass<string> (per esempio come un tipo di parametro), non possono riferimento un tipo generico chiuso tali direttamente. Il secondo esempio funziona risolvere questa limitazione. (Questo è visto ad esempio sul pagina refence MSDN per la System.String.Concat(IEnumerable<string>) metodo statico ). :

regole XML documentazione commento cref:

• Circondano il tipo di elenco di parametri generici con parentesi graffe {} invece che con parentesi angolari <>. In questo modo si risparmia di fuggire il secondo come < e > - ricordate, commenti di documentazione sono XML

• Se si include un prefisso (ad esempio T: per i tipi, M: per i metodi, P: per le proprietà, F: per i campi), il compilatore non eseguire alcuna convalida del riferimento, ma è sufficiente copiare il valore dell'attributo cref dritto all'uscita documentazione XML. Per questo motivo, dovrete usare lo speciale " stringa ID" sintassi che si applica in tali file:. utilizzare sempre identificatori pienamente qualificati, e utilizzare apici inversi per fare riferimento a parametri di tipo generico (`n sui tipi, ``n sui metodi)

• Se si omette il prefisso , si applicano le regole normali lingua di denominazione: si può cadere spazi dei nomi per i quali c'è una dichiarazione using, ed è possibile utilizzare il linguaggio digitare le parole chiave come ad esempio int invece di System.Int32 . Inoltre, il compilatore controllerà il riferimento per correttezza.

documentazione XML commento cref cheat sheet:

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);
    }
}

Answer 4

Nessuna delle risposte indicate finora lavorare completamente per me. ReSharper non converte il tag sede in un Ctrl + link click-in grado (per esempio, ) a meno che non si risolve completamente.

Se il metodo nel PO erano in uno spazio dei nomi chiamato Test, il collegamento completamente risolto con il metodo indicato sarebbe:

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

Come si può essere in grado di elaborare, ci dovrebbe essere un solo backtick prima del numero di parametri di tipo classe, quindi due backticks prima del numero di parametri di tipo metodo, i parametri sono il parametro zero indicizzato con il numero appropriato di backticks.

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

Come si può 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 legame 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 ho trovato questo documentato da nessuna parte e io non sono un genio, il compilatore me tutto questo ha detto. Tutto quello che dovete fare è creare un progetto di test, abilitare documentazione XML , quindi inserire il codice che si desidera elaborare un link per, e mettere l'inizio di un commento di documentazione 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 costruire il vostro progetto e la documentazione XML emesso comprende il collegamento nel> doc-> members elemento member- sotto la name attributo:

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

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

Answer 5

Inoltre dalle risposte di Lasse e T.B.C:

/// <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 correttamente, mentre la loro versione rende con le parentesi.

Answer 6

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

Answer 7

/// <see cref="FancyClass&lt;T>.FancyMethod&lt;K>(T)"/> for more information.