Documentazione XML (F#)
È possibile generare documentazione dai commenti di codice a barra tripla (///) in F#. I commenti XML possono precedere dichiarazioni in file di codice (con estensione fs) o file di firma (con estensione fsi).
Generazione di documenti dai commenti
Il supporto in F# per la generazione di documentazione dai commenti è analogo a quello disponibile in altri linguaggi .NET Framework. Come per gli altri linguaggi .NET Framework, l'opzione -doc del compilatore consente di generare un file XML contenente informazioni che è possibile convertire in documentazione utilizzando uno strumento come Sandcastle. La documentazione generata tramite strumenti progettati per l'utilizzo con assembly scritti in altri linguaggi .NET Framework produce in genere una visualizzazione delle interfacce API basata sul formato compilato dei costrutti F#. A meno che gli strumenti non supportino nello specifico il linguaggio F#, la documentazione generata da questi strumenti non corrisponde alla visualizzazione F# di un'interfaccia API.
Per ulteriori informazioni su come generare documentazione da XML, vedere Commenti relativi alla documentazione XML (Guida per programmatori C#).
Tag consigliati
È possibile scrivere i commenti alla documentazione XML in due modi. Il primo modo consiste nello scrivere direttamente la documentazione con commenti a barra tripla, senza utilizzare tag XML. In questo caso, l'intero testo del commento viene utilizzato come documentazione riepilogativa per il costrutto di codice immediatamente seguente. Utilizzare questo metodo se si desidera scrivere esclusivamente un breve riepilogo per ogni costrutto. L'altro metodo consiste nell'utilizzare tag XML per fornire documentazione più strutturata. Il secondo modo consente di specificare note separate per un breve riepilogo, commenti aggiuntivi, documentazione per ogni parametro e parametro di tipo ed eccezioni generate, nonché descrizione del valore restituito. Nella tabella seguente vengono descritti i tag XML riconosciuti nei commenti del codice XML di F#.
Sintassi dei tag |
Descrizione |
|---|---|
<c> testo </c> |
Specifica che il testo è costituito da codice. Questo tag può essere utilizzato dai generatori di documentazione per visualizzare il testo in un tipo di carattere appropriato per il codice. |
<summary> testo </summary> |
Specifica che il testo consiste in una breve descrizione dell'elemento del programma. La descrizione è generalmente costituita da una o due frasi. |
<remarks> testo </remarks> |
Specifica che il testo contiene informazioni aggiuntive sull'elemento del programma. |
<param name="nome"> descrizione </param> |
Specifica il nome e la descrizione per una funzione o un parametro del metodo. |
<typeparam name="nome"> descrizione </typeparam> |
Specifica il nome e la descrizione per un parametro del tipo. |
<returns> testo </returns> |
Specifica che il testo descrive il valore restituito di una funzione o di un metodo. |
<exception cref="tipo"> descrizione </exception> |
Specifica il tipo di eccezione e le circostanze in base alle quali può essere generata. |
<see cref="riferimento"> testo </see> |
Specifica un collegamento inline a un altro elemento del programma. Il riferimento è il nome visualizzato nel file di documentazione XML. Il testo è il testo visualizzato nel collegamento. |
<seealso cref="Riferimento "/> |
Specifica un collegamento Vedere anche alla documentazione per un altro tipo. Il riferimento è il nome visualizzato nel file di documentazione XML. I collegamenti Vedere anche sono in genere visualizzati nella parte inferiore di una pagina della documentazione. |
<para> testo </para> |
Specifica un paragrafo di testo. Viene utilizzato per separare il testo nel tag remarks. |
Esempio
Descrizione
Di seguito è indicato un commento tipico relativo alla documentazione XML in un file di firma.
Codice
/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each of the characters of the input string and concatenating the resulting
/// strings.</summary>
/// <param name="mapping">The function to produce a string from each character of the input string.</param>
///<param name="str">The input string.</param>
///<returns>The concatenated string.</returns>
///<exception cref="System.ArgumentNullException">Thrown when the input string is null.</exception>
val collect : (char -> string) -> string -> string
Esempio
Descrizione
Nell'esempio seguente viene illustrato il metodo alternativo, senza tag XML. In questo esempio, l'intero testo nel commento viene considerato un riepilogo. Se non si specifica in modo esplicito un tag riepilogativo, non specificare altri tag, ad esempio param o returns.
Codice
/// Creates a new string whose characters are the result of applying
/// the function mapping to each of the characters of the input string
/// and concatenating the resulting strings.
val collect : (char -> string) -> string -> string