Documentare il tuo codice con commenti XMLDocumentare il tuo codice con commenti XML

  • 01/21/2020
  • 18 minuti per leggere
    • B
    • o
    • O

I commenti alla documentazione XML sono un tipo speciale di commento, aggiunto sopra la definizione di un tipo o membro definito dall’utente.I commenti della documentazione XML sono un tipo speciale di commento, aggiunto sopra la definizione di qualsiasi tipo o membro definito dall’utente.Sono speciali perché possono essere processati dal compilatore per generare un file di documentazione XML al momento della compilazione.Il file XML generato dal compilatore può essere distribuito con il tuo .NET in modo che Visual Studio e altri IDE possano usare IntelliSense per mostrare informazioni rapide su tipi o membri. Inoltre, il file XML può essere eseguito attraverso strumenti come DocFX e Sandcastle per generare siti web di riferimento API.

I commenti della documentazione XML, come tutti gli altri commenti, sono ignorati dal compilatore.

È possibile generare il file XML in fase di compilazione facendo una delle seguenti cose:

  • Se si sviluppa un’applicazione con .NET Core dalla riga di comando, potete aggiungere un elemento GenerateDocumentationFile alla sezione <PropertyGroup> del vostro file di progetto. csproj.Se state sviluppando un’applicazione con .NET Core dalla riga di comando, potete aggiungere un elemento GenerateDocumentationFile alla sezione <PropertyGroup> del vostro file di progetto .csproj. Puoi anche specificare il percorso del file di documentazione direttamente usando l’elemento DocumentationFile. L’esempio seguente genera un file XML nella directory del progetto con lo stesso nome di file radice dell’assieme:The following example generates an XML file in the project directory with the same root filename as the assembly:

    <GenerateDocumentationFile>true</GenerateDocumentationFile>

    è equivalente a questo:

    <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  • Se state sviluppando un’applicazione utilizzando Visual Studio, cliccate con il tasto destro del mouse sul progetto, quindi selezionate Proprietà.Se state sviluppando un’applicazione usando Visual Studio, cliccate con il tasto destro sul progetto e selezionate Proprietà. Nella finestra di dialogo delle proprietà, selezionate la scheda Build e controllate il file di documentazione XML. Puoi anche cambiare la posizione in cui il compilatore scrive il file.

  • Se stai compilando un file .NET dalla riga di comando, aggiungere l’opzione -doc del compilatore durante la compilazione.

I commenti della documentazione XML usano triple barre in avanti (///) e un corpo di commento formattato in XML. Per esempio:

/// <summary>/// This class does something./// </summary>public class SomeClass{}

Procedura passo-passoWalkthrough

Documentiamo una libreria matematica molto semplice per renderla facile da capire/contribuire per i nuovi sviluppatori e da usare per gli sviluppatori di terze parti.

Ecco il codice per la libreria matematica semplice:Ecco il codice per la libreria matematica semplice:

/* The main Math class Contains all methods for performing basic math functions*/public class Math{ // Adds two integers and returns the result public static int Add(int a, int b) { // If any parameter is equal to the max value of an integer // and the other is greater than zero if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; } // Adds two doubles and returns the result public static double Add(double a, double b) { if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; } // Subtracts an integer from another and returns the result public static int Subtract(int a, int b) { return a - b; } // Subtracts a double from another and returns the result public static double Subtract(double a, double b) { return a - b; } // Multiplies two integers and returns the result public static int Multiply(int a, int b) { return a * b; } // Multiplies two doubles and returns the result public static double Multiply(double a, double b) { return a * b; } // Divides an integer by another and returns the result public static int Divide(int a, int b) { return a / b; } // Divides a double by another and returns the result public static double Divide(double a, double b) { return a / b; }}

La libreria di esempio supporta quattro operazioni aritmetiche principali ( addsubtractmultiply e divide ) su int tipi di double dati e.La libreria di esempio supporta quattro operazioni aritmetiche principali (addsubtractmultiply, e divide) sui tipi di dati int e double.

Ora volete essere in grado di creare un documento di riferimento API dal vostro codice per gli sviluppatori di terze parti che usano la vostra libreria, ma non hanno accesso al codice sorgente.Ora volete essere in grado di creare un documento di riferimento API dal vostro codice per gli sviluppatori di terze parti che usano la vostra libreria ma non hanno accesso al codice sorgente. Ora sarete introdotti ai tag XML standard che il compilatore C# supporta.

<summary>

Il tag <summary> aggiunge informazioni succinte su un tipo o un membro.Il tag <summary> aggiunge brevi informazioni su un tipo o un membro. dimostrerò il suo uso aggiungendolo alla definizione della classe Math e al primo metodo Add.Dimostrerò il suo uso aggiungendolo alla definizione della classe Math e al primo metodo Add. Sentitevi liberi di applicarlo al resto del vostro codice.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main Math class./// Contains all methods for performing basic math functions./// </summary>public class Math{ // Adds two integers and returns the result /// <summary> /// Adds two integers and returns the result. /// </summary> public static int Add(int a, int b) { // If any parameter is equal to the max value of an integer // and the other is greater than zero if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; }}

Il tag <summary> è importante e vi raccomandiamo di includerlo poiché il suo contenuto è la fonte primaria di informazioni sul tipo o sul membro in IntelliSense o in un documento di riferimento API.Il tag <summary> è importante, e si raccomanda di includerlo perché il suo contenuto è la fonte principale di informazioni sul tipo o sul membro in IntelliSense o in un documento di riferimento API.

< osservazioni>

Il tag <remarks> completa il tipo o le informazioni sul membro fornite dal tag <summary>.Il tag <remarks> completa le informazioni sui tipi o sui membri che il tag <summary> fornisce. In questo esempio, lo aggiungerete semplicemente alla classe.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main Math class./// Contains all methods for performing basic math functions./// </summary>/// <remarks>/// This class can add, subtract, multiply and divide./// </remarks>public class Math{}

<returns>

Il tag <returns> fornisce una descrizione del valore di ritorno di una dichiarazione di metodo.Il tag <returns> descrive il valore di ritorno di una dichiarazione di metodo.Come prima, l’esempio seguente illustra il tag <returns> sul primo metodo Add.Come prima, l’esempio seguente illustra il tag <returns> sul primo metodo Add. Potete fare lo stesso con altri metodi.

// Adds two integers and returns the result/// <summary>/// Adds two integers and returns the result./// </summary>/// <returns>/// The sum of two integers./// </returns>public static int Add(int a, int b){ // If any parameter is equal to the max value of an integer // and the other is greater than zero if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b;}

<value>

Il tag <value> è simile al tag <returns>, tranne che lo si usa per le proprietà.Il tag <value> è simile al tag <returns>, eccetto che lo si usa per le proprietà.Supponendo che la tua libreria Math abbia una proprietà statica chiamata PI, ecco come dovresti usare questo tag:Assumendo che la tua libreria Math abbia una proprietà statica chiamata PI, ecco come dovresti usare questo tag:

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main Math class./// Contains all methods for performing basic math functions./// </summary>/// <remarks>/// This class can add, subtract, multiply and divide./// These operations can be performed on both integers and doubles/// </remarks>public class Math{ /// <value>Gets the value of PI.</value> public static double PI { get; }}

<example>

Il tag <example> ti permette di includere un esempio della tua documentazione XML.Usate il tag <example> per includere un esempio nella vostra documentazione XML. Questo comporta l’uso del tag figlio <code>.Questo comporta l’utilizzo del tag figlio <code>.

// Adds two integers and returns the result/// <summary>/// Adds two integers and returns the result./// </summary>/// <returns>/// The sum of two integers./// </returns>/// <example>/// <code>/// int c = Math.Add(4, 5);/// if (c > 10)/// {/// Console.WriteLine(c);/// }/// </code>/// </example>public static int Add(int a, int b){ // If any parameter is equal to the max value of an integer // and the other is greater than zero if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b;}

Il tag code mantiene le interruzioni di riga e l’indentazione per gli esempi più lunghi.Il tag code conserva le interruzioni di riga e l’indentazione per gli esempi più lunghi.

<para>

Il tag <para> formatta il contenuto all’interno del suo tag padre. <para> è solitamente usato in un tag, come <remarks> o <returns>, per spezzare il testo in paragrafi.<para> è solitamente usato all’interno di un tag, come <remarks> o <returns>, per dividere il testo in paragrafi.Puoi formattare il contenuto del tag <remarks> per la definizione della tua classe.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main Math class./// Contains all methods for performing basic math functions./// </summary>/// <remarks>/// <para>This class can add, subtract, multiply and divide.</para>/// <para>These operations can be performed on both integers and doubles.</para>/// </remarks>public class Math{}

<c>

Sempre in tema di formattazione, si usa il tag <c> per marcare parte del testo come codice.Sempre in tema di formattazione, si usa il tag <c> per marcare una parte di testo come codice. è come il tag <code> ma in linea. È utile quando si vuole mostrare un rapido esempio di codice come parte del contenuto di un tag. Aggiorniamo la documentazione per la classe Math.Aggiorniamo la documentazione per la classe Math.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// </summary>public class Math{}

<exception>

Utilizzando il tag <exception>, state informando i vostri sviluppatori che un metodo può sollevare eccezioni specifiche.Usando il tag <exception>, fate sapere ai vostri sviluppatori che un metodo può lanciare eccezioni specifiche. Se guardate la vostra libreria Math, potete vedere che entrambi i metodi Add lanciano un’eccezione se si verifica una certa condizione.Guardando la tua libreria Math, puoi vedere che entrambi i metodi Add lanciano un’eccezione se si verifica una certa condizione. È meno ovvio, però, che il metodo Divide usato con un intero lancia anche un’eccezione se il parametro b è zero. Ora aggiungete la documentazione delle eccezioni a questo metodo.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// </summary>public class Math{ /// <summary> /// Adds two integers and returns the result. /// </summary> /// <returns> /// The sum of two integers. /// </returns> /// <example> /// <code> /// int c = Math.Add(4, 5); /// if (c > 10) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than 0.</exception> public static int Add(int a, int b) { if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; } /// <summary> /// Adds two doubles and returns the result. /// </summary> /// <returns> /// The sum of two doubles. /// </returns> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than zero.</exception> public static double Add(double a, double b) { if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; } /// <summary> /// Divides an integer by another and returns the result. /// </summary> /// <returns> /// The division of two integers. /// </returns> /// <exception cref="System.DivideByZeroException">Thrown when a division by zero occurs.</exception> public static int Divide(int a, int b) { return a / b; } /// <summary> /// Divides a double by another and returns the result. /// </summary> /// <returns> /// The division of two doubles. /// </returns> /// <exception cref="System.DivideByZeroException">Thrown when a division by zero occurs.</exception> public static double Divide(double a, double b) { return a / b; }}

L’attributo cref fa riferimento a un’eccezione che è disponibile nell’ambiente di costruzione corrente.L’attributo cref rappresenta un riferimento a un’eccezione disponibile nell’ambiente di compilazione corrente, che può essere qualsiasi tipo definito nel progetto o un assembly di riferimento. Il compilatore emetterà un avviso se il suo valore non può essere risolto.

<see>

Il tag <see> permette di creare un collegamento interattivo ad una pagina di documentazione per un altro pezzo di codice.Il tag <see> permette di creare un collegamento cliccabile a una pagina di documentazione per un altro elemento del codice. Nel nostro prossimo esempio, creeremo un link cliccabile tra i due metodi Add.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// </summary>public class Math{ /// <summary> /// Adds two integers and returns the result. /// </summary> /// <returns> /// The sum of two integers. /// </returns> /// <example> /// <code> /// int c = Math.Add(4, 5); /// if (c > 10) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than 0.</exception> /// See <see cref="Math.Add(double, double)"/> to add doubles. public static int Add(int a, int b) { if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; } /// <summary> /// Adds two doubles and returns the result. /// </summary> /// <returns> /// The sum of two doubles. /// </returns> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than zero.</exception> /// See <see cref="Math.Add(int, int)"/> to add integers. public static double Add(double a, double b) { if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; }}

cref è un attributo richiesto che rappresenta un riferimento a un tipo o ai suoi membri che è disponibile nell’ambiente di compilazione corrente.Questo può essere qualsiasi tipo definito nel progetto o un assembly di riferimento.

<seealso>

Puoi usare il tag <seealso> come il tag <see>.Si usa il tag <seealso> nello stesso modo in cui si usa il tag <see>. L’unica differenza è che il suo contenuto è tipicamente collocato in una sezione “Vedi anche”. Qui aggiungeremo un tag seealso sotto il metodo Add usato con un intero per fare riferimento ad altri metodi nella classe che accettano parametri interi:Qui aggiungeremo un tag seealso sul metodo integer Add per fare riferimento ad altri metodi nella classe che accettano parametri interi:

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// </summary>public class Math{ /// <summary> /// Adds two integers and returns the result. /// </summary> /// <returns> /// The sum of two integers. /// </returns> /// <example> /// <code> /// int c = Math.Add(4, 5); /// if (c > 10) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than 0.</exception> /// See <see cref="Math.Add(double, double)"/> to add doubles. /// <seealso cref="Math.Subtract(int, int)"/> /// <seealso cref="Math.Multiply(int, int)"/> /// <seealso cref="Math.Divide(int, int)"/> public static int Add(int a, int b) { if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; }}

L’attributo cref rappresenta un riferimento a un tipo o ai suoi membri ed è disponibile nell’ambiente di compilazione corrente.L’attributo cref rappresenta un riferimento a un tipo o a un suo membro che è disponibile nell’ambiente di compilazione corrente, che può essere qualsiasi tipo definito nel progetto o un assembly di riferimento.

<param>

Il tag <param> è usato per descrivere i parametri di un metodo. Ecco un esempio sul metodo doppio Add: il parametro che il tag descrive è specificato nell’attributo Required name.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// </summary>public class Math{ /// <summary> /// Adds two doubles and returns the result. /// </summary> /// <returns> /// The sum of two doubles. /// </returns> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than zero.</exception> /// See <see cref="Math.Add(int, int)"/> to add integers. /// <param name="a">A double precision number.</param> /// <param name="b">A double precision number.</param> public static double Add(double a, double b) { if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; }}

<typeparam>

Si usa il tag <typeparam> proprio come il tag <param>, ma per permettere alle dichiarazioni di tipi o metodi generici di descrivere un parametro generico.Si usa il tag <typeparam> proprio come il tag <param> ma per le dichiarazioni di tipi o metodi generici per descrivere un parametro generico.Aggiungete un metodo generico veloce alla vostra classe Math per controllare se una quantità è maggiore di un’altra.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// </summary>public class Math{ /// <summary> /// Checks if an IComparable is greater than another. /// </summary> /// <typeparam name="T">A type that inherits from the IComparable interface.</typeparam> public static bool GreaterThan<T>(T a, T b) where T : IComparable { return a.CompareTo(b) > 0; }}

<paramref>

Mentre stai descrivendo cosa fa un metodo in quello che potrebbe essere un tag <summary>, potresti voler creare un riferimento a un parametro.A volte potreste essere nel mezzo della descrizione di cosa fa un metodo in quello che potrebbe essere un tag <summary>, e potreste voler fare un riferimento a un parametro. Il tag <paramref> è ottimo per questo compito. Aggiorniamo il sommario del nostro metodo Add basato sul doppio. Come il tag <param>, il nome del parametro è specificato nell’attributo Required name.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// </summary>public class Math{ /// <summary> /// Adds two doubles <paramref name="a"/> and <paramref name="b"/> and returns the result. /// </summary> /// <returns> /// The sum of two doubles. /// </returns> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than zero.</exception> /// See <see cref="Math.Add(int, int)"/> to add integers. /// <param name="a">A double precision number.</param> /// <param name="b">A double precision number.</param> public static double Add(double a, double b) { if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; }}

<typeparamref>

Si usa il tag <typeparamref> proprio come il tag <paramref>, ma per permettere alle dichiarazioni di tipi o metodi generici di descrivere un parametro generico.Si usa il tag <typeparamref> proprio come il tag <paramref> ma per le dichiarazioni di tipo o metodo generico per descrivere un parametro generico.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// </summary>public class Math{ /// <summary> /// Checks if an IComparable <typeparamref name="T"/> is greater than another. /// </summary> /// <typeparam name="T">A type that inherits from the IComparable interface.</typeparam> public static bool GreaterThan<T>(T a, T b) where T : IComparable { return a.CompareTo(b) > 0; }}

<list>

Si usa il tag <list> per formattare le informazioni della documentazione come una lista ordinata, un elenco non ordinato o una tabella.Si usa il tag <list> per formattare le informazioni della documentazione come elenco ordinato, elenco non ordinato o tabella. Crea una lista non ordinata di ogni operazione matematica che la tua Math libreria supporta.

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// <list type="bullet">/// <item>/// <term>Add</term>/// <description>Addition Operation</description>/// </item>/// <item>/// <term>Subtract</term>/// <description>Subtraction Operation</description>/// </item>/// <item>/// <term>Multiply</term>/// <description>Multiplication Operation</description>/// </item>/// <item>/// <term>Divide</term>/// <description>Division Operation</description>/// </item>/// </list>/// </summary>public class Math{}

Puoi fare un elenco ordinato o una tabella sostituendo l’attributo type con number o table, rispettivamente.Puoi fare un elenco ordinato o una tabella cambiando l’attributo type in number o table, rispettivamente.

<inheritdoc>

È possibile utilizzare il tag <inheritdoc> per ereditare commenti XML da classi base, interfacce e metodi simili.Potete usare il tag <inheritdoc> per ereditare commenti XML da classi base, interfacce e metodi simili. Questo elimina il copia e incolla indesiderato di commenti XML duplicati e mantiene automaticamente sincronizzati i commenti XML.

/* The IMath interface The main Math class Contains all methods for performing basic math functions*//// <summary>/// This is the IMath interface./// </summary>public interface IMath{}/// <inheritdoc/>public class Math : IMath{}

AssemblaggioMettere tutto insieme

Se avete seguito questo tutorial e applicato i tag al vostro codice come necessario, il vostro codice dovrebbe ora essere come il seguente:Se avete seguito questo tutorial e applicato i tag al vostro codice dove necessario, il vostro codice dovrebbe ora essere simile al seguente:

/* The main Math class Contains all methods for performing basic math functions*//// <summary>/// The main <c>Math</c> class./// Contains all methods for performing basic math functions./// <list type="bullet">/// <item>/// <term>Add</term>/// <description>Addition Operation</description>/// </item>/// <item>/// <term>Subtract</term>/// <description>Subtraction Operation</description>/// </item>/// <item>/// <term>Multiply</term>/// <description>Multiplication Operation</description>/// </item>/// <item>/// <term>Divide</term>/// <description>Division Operation</description>/// </item>/// </list>/// </summary>/// <remarks>/// <para>This class can add, subtract, multiply and divide.</para>/// <para>These operations can be performed on both integers and doubles.</para>/// </remarks>public class Math{ // Adds two integers and returns the result /// <summary> /// Adds two integers <paramref name="a"/> and <paramref name="b"/> and returns the result. /// </summary> /// <returns> /// The sum of two integers. /// </returns> /// <example> /// <code> /// int c = Math.Add(4, 5); /// if (c > 10) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than 0.</exception> /// See <see cref="Math.Add(double, double)"/> to add doubles. /// <seealso cref="Math.Subtract(int, int)"/> /// <seealso cref="Math.Multiply(int, int)"/> /// <seealso cref="Math.Divide(int, int)"/> /// <param name="a">An integer.</param> /// <param name="b">An integer.</param> public static int Add(int a, int b) { // If any parameter is equal to the max value of an integer // and the other is greater than zero if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; } // Adds two doubles and returns the result /// <summary> /// Adds two doubles <paramref name="a"/> and <paramref name="b"/> and returns the result. /// </summary> /// <returns> /// The sum of two doubles. /// </returns> /// <example> /// <code> /// double c = Math.Add(4.5, 5.4); /// if (c > 10) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// <exception cref="System.OverflowException">Thrown when one parameter is max /// and the other is greater than 0.</exception> /// See <see cref="Math.Add(int, int)"/> to add integers. /// <seealso cref="Math.Subtract(double, double)"/> /// <seealso cref="Math.Multiply(double, double)"/> /// <seealso cref="Math.Divide(double, double)"/> /// <param name="a">A double precision number.</param> /// <param name="b">A double precision number.</param> public static double Add(double a, double b) { // If any parameter is equal to the max value of an integer // and the other is greater than zero if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; } // Subtracts an integer from another and returns the result /// <summary> /// Subtracts <paramref name="b"/> from <paramref name="a"/> and returns the result. /// </summary> /// <returns> /// The difference between two integers. /// </returns> /// <example> /// <code> /// int c = Math.Subtract(4, 5); /// if (c > 1) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// See <see cref="Math.Subtract(double, double)"/> to subtract doubles. /// <seealso cref="Math.Add(int, int)"/> /// <seealso cref="Math.Multiply(int, int)"/> /// <seealso cref="Math.Divide(int, int)"/> /// <param name="a">An integer.</param> /// <param name="b">An integer.</param> public static int Subtract(int a, int b) { return a - b; } // Subtracts a double from another and returns the result /// <summary> /// Subtracts a double <paramref name="b"/> from another double <paramref name="a"/> and returns the result. /// </summary> /// <returns> /// The difference between two doubles. /// </returns> /// <example> /// <code> /// double c = Math.Subtract(4.5, 5.4); /// if (c > 1) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// See <see cref="Math.Subtract(int, int)"/> to subtract integers. /// <seealso cref="Math.Add(double, double)"/> /// <seealso cref="Math.Multiply(double, double)"/> /// <seealso cref="Math.Divide(double, double)"/> /// <param name="a">A double precision number.</param> /// <param name="b">A double precision number.</param> public static double Subtract(double a, double b) { return a - b; } // Multiplies two integers and returns the result /// <summary> /// Multiplies two integers <paramref name="a"/> and <paramref name="b"/> and returns the result. /// </summary> /// <returns> /// The product of two integers. /// </returns> /// <example> /// <code> /// int c = Math.Multiply(4, 5); /// if (c > 100) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// See <see cref="Math.Multiply(double, double)"/> to multiply doubles. /// <seealso cref="Math.Add(int, int)"/> /// <seealso cref="Math.Subtract(int, int)"/> /// <seealso cref="Math.Divide(int, int)"/> /// <param name="a">An integer.</param> /// <param name="b">An integer.</param> public static int Multiply(int a, int b) { return a * b; } // Multiplies two doubles and returns the result /// <summary> /// Multiplies two doubles <paramref name="a"/> and <paramref name="b"/> and returns the result. /// </summary> /// <returns> /// The product of two doubles. /// </returns> /// <example> /// <code> /// double c = Math.Multiply(4.5, 5.4); /// if (c > 100.0) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// See <see cref="Math.Multiply(int, int)"/> to multiply integers. /// <seealso cref="Math.Add(double, double)"/> /// <seealso cref="Math.Subtract(double, double)"/> /// <seealso cref="Math.Divide(double, double)"/> /// <param name="a">A double precision number.</param> /// <param name="b">A double precision number.</param> public static double Multiply(double a, double b) { return a * b; } // Divides an integer by another and returns the result /// <summary> /// Divides an integer <paramref name="a"/> by another integer <paramref name="b"/> and returns the result. /// </summary> /// <returns> /// The quotient of two integers. /// </returns> /// <example> /// <code> /// int c = Math.Divide(4, 5); /// if (c > 1) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// <exception cref="System.DivideByZeroException">Thrown when <paramref name="b"/> is equal to 0.</exception> /// See <see cref="Math.Divide(double, double)"/> to divide doubles. /// <seealso cref="Math.Add(int, int)"/> /// <seealso cref="Math.Subtract(int, int)"/> /// <seealso cref="Math.Multiply(int, int)"/> /// <param name="a">An integer dividend.</param> /// <param name="b">An integer divisor.</param> public static int Divide(int a, int b) { return a / b; } // Divides a double by another and returns the result /// <summary> /// Divides a double <paramref name="a"/> by another double <paramref name="b"/> and returns the result. /// </summary> /// <returns> /// The quotient of two doubles. /// </returns> /// <example> /// <code> /// double c = Math.Divide(4.5, 5.4); /// if (c > 1.0) /// { /// Console.WriteLine(c); /// } /// </code> /// </example> /// <exception cref="System.DivideByZeroException">Thrown when <paramref name="b"/> is equal to 0.</exception> /// See <see cref="Math.Divide(int, int)"/> to divide integers. /// <seealso cref="Math.Add(double, double)"/> /// <seealso cref="Math.Subtract(double, double)"/> /// <seealso cref="Math.Multiply(double, double)"/> /// <param name="a">A double precision dividend.</param> /// <param name="b">A double precision divisor.</param> public static double Divide(double a, double b) { return a / b; }}

Dal vostro codice, potete generare un sito web di documentazione dettagliata completo di riferimenti incrociati interattivi.Dal vostro codice, potete generare un sito web di documentazione dettagliata completo di riferimenti incrociati cliccabili. Ma vi trovate di fronte a un altro problema: il vostro codice è diventato difficile da leggere, ci sono così tante informazioni da setacciare che questo sarà un incubo per qualsiasi sviluppatore che voglia contribuire a questo codice.Per fortuna c’è un tag XML che può aiutarvi ad affrontare questo problema:Thankfully there’s an XML tag that can help you deal with this problem:Per fortuna c’è un tag XML che può aiutarvi ad affrontare questo problema:

<include>

Il tag <include> vi permette di fare riferimento a commenti trovati in un file XML separato che descrive i tipi e i membri del vostro codice sorgente invece di mettere commenti di documentazione direttamente nel vostro file di codice sorgente.Il tag <include> ti permette di fare riferimento a commenti in un file XML separato che descrivono i tipi e i membri nel tuo codice sorgente, invece di mettere commenti di documentazione direttamente nel tuo file di codice sorgente.

Ora sposterai tutti i tuoi tag XML in un file XML separato chiamato docs.xml. Sentitevi liberi di dare al file il nome che volete.

<docs> <members name="math"> <Math> <summary> The main <c>Math</c> class. Contains all methods for performing basic math functions. </summary> <remarks> <para>This class can add, subtract, multiply and divide.</para> <para>These operations can be performed on both integers and doubles.</para> </remarks> </Math> <AddInt> <summary> Adds two integers <paramref name="a"/> and <paramref name="b"/> and returns the result. </summary> <returns> The sum of two integers. </returns> <example> <code> int c = Math.Add(4, 5); if (c > 10) { Console.WriteLine(c); } </code> </example> <exception cref="System.OverflowException">Thrown when one parameter is max and the other is greater than 0.</exception> See <see cref="Math.Add(double, double)"/> to add doubles. <seealso cref="Math.Subtract(int, int)"/> <seealso cref="Math.Multiply(int, int)"/> <seealso cref="Math.Divide(int, int)"/> <param name="a">An integer.</param> <param name="b">An integer.</param> </AddInt> <AddDouble> <summary> Adds two doubles <paramref name="a"/> and <paramref name="b"/> and returns the result. </summary> <returns> The sum of two doubles. </returns> <example> <code> double c = Math.Add(4.5, 5.4); if (c > 10) { Console.WriteLine(c); } </code> </example> <exception cref="System.OverflowException">Thrown when one parameter is max and the other is greater than 0.</exception> See <see cref="Math.Add(int, int)"/> to add integers. <seealso cref="Math.Subtract(double, double)"/> <seealso cref="Math.Multiply(double, double)"/> <seealso cref="Math.Divide(double, double)"/> <param name="a">A double precision number.</param> <param name="b">A double precision number.</param> </AddDouble> <SubtractInt> <summary> Subtracts <paramref name="b"/> from <paramref name="a"/> and returns the result. </summary> <returns> The difference between two integers. </returns> <example> <code> int c = Math.Subtract(4, 5); if (c > 1) { Console.WriteLine(c); } </code> </example> See <see cref="Math.Subtract(double, double)"/> to subtract doubles. <seealso cref="Math.Add(int, int)"/> <seealso cref="Math.Multiply(int, int)"/> <seealso cref="Math.Divide(int, int)"/> <param name="a">An integer.</param> <param name="b">An integer.</param> </SubtractInt> <SubtractDouble> <summary> Subtracts a double <paramref name="b"/> from another double <paramref name="a"/> and returns the result. </summary> <returns> The difference between two doubles. </returns> <example> <code> double c = Math.Subtract(4.5, 5.4); if (c > 1) { Console.WriteLine(c); } </code> </example> See <see cref="Math.Subtract(int, int)"/> to subtract integers. <seealso cref="Math.Add(double, double)"/> <seealso cref="Math.Multiply(double, double)"/> <seealso cref="Math.Divide(double, double)"/> <param name="a">A double precision number.</param> <param name="b">A double precision number.</param> </SubtractDouble> <MultiplyInt> <summary> Multiplies two integers <paramref name="a"/> and <paramref name="b"/> and returns the result. </summary> <returns> The product of two integers. </returns> <example> <code> int c = Math.Multiply(4, 5); if (c > 100) { Console.WriteLine(c); } </code> </example> See <see cref="Math.Multiply(double, double)"/> to multiply doubles. <seealso cref="Math.Add(int, int)"/> <seealso cref="Math.Subtract(int, int)"/> <seealso cref="Math.Divide(int, int)"/> <param name="a">An integer.</param> <param name="b">An integer.</param> </MultiplyInt> <MultiplyDouble> <summary> Multiplies two doubles <paramref name="a"/> and <paramref name="b"/> and returns the result. </summary> <returns> The product of two doubles. </returns> <example> <code> double c = Math.Multiply(4.5, 5.4); if (c > 100.0) { Console.WriteLine(c); } </code> </example> See <see cref="Math.Multiply(int, int)"/> to multiply integers. <seealso cref="Math.Add(double, double)"/> <seealso cref="Math.Subtract(double, double)"/> <seealso cref="Math.Divide(double, double)"/> <param name="a">A double precision number.</param> <param name="b">A double precision number.</param> </MultiplyDouble> <DivideInt> <summary> Divides an integer <paramref name="a"/> by another integer <paramref name="b"/> and returns the result. </summary> <returns> The quotient of two integers. </returns> <example> <code> int c = Math.Divide(4, 5); if (c > 1) { Console.WriteLine(c); } </code> </example> <exception cref="System.DivideByZeroException">Thrown when <paramref name="b"/> is equal to 0.</exception> See <see cref="Math.Divide(double, double)"/> to divide doubles. <seealso cref="Math.Add(int, int)"/> <seealso cref="Math.Subtract(int, int)"/> <seealso cref="Math.Multiply(int, int)"/> <param name="a">An integer dividend.</param> <param name="b">An integer divisor.</param> </DivideInt> <DivideDouble> <summary> Divides a double <paramref name="a"/> by another double <paramref name="b"/> and returns the result. </summary> <returns> The quotient of two doubles. </returns> <example> <code> double c = Math.Divide(4.5, 5.4); if (c > 1.0) { Console.WriteLine(c); } </code> </example> <exception cref="System.DivideByZeroException">Thrown when <paramref name="b"/> is equal to 0.</exception> See <see cref="Math.Divide(int, int)"/> to divide integers. <seealso cref="Math.Add(double, double)"/> <seealso cref="Math.Subtract(double, double)"/> <seealso cref="Math.Multiply(double, double)"/> <param name="a">A double precision dividend.</param> <param name="b">A double precision divisor.</param> </DivideDouble> </members></docs>

Nell’XML di cui sopra, i commenti sulla documentazione di ogni membro appaiono direttamente all’interno di un tag che porta il nome di ciò che fanno. Potete scegliere la vostra strategia.Ora che avete i vostri commenti XML in un file separato, vediamo come il vostro codice può essere reso più leggibile usando il tag <include>:Ora che avete i vostri commenti XML in un file separato, vediamo come il vostro codice può essere reso più leggibile usando il tag <include>:

/* The main Math class Contains all methods for performing basic math functions*//// <include file='docs.xml' path='docs/members/Math/*'/>public class Math{ // Adds two integers and returns the result /// <include file='docs.xml' path='docs/members/AddInt/*'/> public static int Add(int a, int b) { // If any parameter is equal to the max value of an integer // and the other is greater than zero if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; } // Adds two doubles and returns the result /// <include file='docs.xml' path='docs/members/AddDouble/*'/> public static double Add(double a, double b) { // If any parameter is equal to the max value of an integer // and the other is greater than zero if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) throw new System.OverflowException(); return a + b; } // Subtracts an integer from another and returns the result /// <include file='docs.xml' path='docs/members/SubtractInt/*'/> public static int Subtract(int a, int b) { return a - b; } // Subtracts a double from another and returns the result /// <include file='docs.xml' path='docs/members/SubtractDouble/*'/> public static double Subtract(double a, double b) { return a - b; } // Multiplies two integers and returns the result /// <include file='docs.xml' path='docs/members/MultiplyInt/*'/> public static int Multiply(int a, int b) { return a * b; } // Multiplies two doubles and returns the result /// <include file='docs.xml' path='docs/members/MultiplyDouble/*'/> public static double Multiply(double a, double b) { return a * b; } // Divides an integer by another and returns the result /// <include file='docs.xml' path='docs/members/DivideInt/*'/> public static int Divide(int a, int b) { return a / b; } // Divides a double by another and returns the result /// <include file='docs.xml' path='docs/members/DivideDouble/*'/> public static double Divide(double a, double b) { return a / b; }}

Ed ecco fatto: il nostro codice è di nuovo leggibile, e nessuna informazione sulla documentazione è stata persa.Ed ecco fatto: il nostro codice è tornato ad essere leggibile, e nessuna informazione sulla documentazione è stata persa.

L’attributo file rappresenta il nome del file XML contenente la documentazione.L’attributo file rappresenta il nome del file XML contenente la documentazione.

L’attributo path rappresenta una query XPath al tag name presente nel file specificato.L’attributo path rappresenta una query XPath al tag name presente nel file specificato.L’attributo name rappresenta lo specificatore del nome nel tag che precede i commenti.

L’attributo id, che può essere usato al posto di name , rappresenta l’ID del tag che precede i commenti.L’attributo id, che può essere usato al posto di name, rappresenta l’ID del tag che precede i commenti. Tuttavia, un utente è libero di definire i propri tag.Strumenti come Sandcastle portano il supporto per tag aggiuntivi come <event> e <note>, e supportano anche la documentazione dello spazio dei nomi.Strumenti come Sandcastle portano il supporto per tag extra come <event> e <note>, e supportano persino la documentazione dei namespace.Gli strumenti di generazione di documentazione personalizzati o in-house possono anche essere usati con i tag standard e possono essere supportati più formati di output da HTML a PDF.

RaccomandazioniRaccomandazioni

La documentazione del codice è raccomandata per molte ragioni. Quelle che seguono sono alcune buone pratiche, scenari generali di casi d’uso e cose che dovreste sapere quando usate i tag di documentazione XML nel vostro codice C#.

  • Per coerenza, tutti i tipi pubblicamente visibili e i loro membri dovrebbero essere documentati. Se dovete farlo, fatelo tutto.
  • I membri privati possono anche essere documentati usando commenti XML. Tuttavia, questo espone il funzionamento interno (potenzialmente confidenziale) della vostra biblioteca.
  • Come minimo, i tipi e i loro membri dovrebbero avere un tag <summary> perché il suo contenuto è necessario per IntelliSense.
  • Il testo della documentazione dovrebbe essere scritto usando frasi complete che terminano con punti.
  • Le classi parziali sono pienamente supportate, e le informazioni sulla documentazione saranno concatenate in una singola voce per quel tipo.
  • Il compilatore controlla la sintassi di <exception><include> tag,,,, <param><see><seealso> e <typeparam> .Il compilatore verifica la sintassi del <exception><include><param><see><seealso>, e <typeparam> tag.
  • Il compilatore convalida i parametri che contengono percorsi di file e riferimenti ad altre parti del codice.

Vedi ancheVedi anche

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *