Documentare il codice con commenti XML

Articolo
03/05/2024

È possibile produrre documentazione da commenti di codice a barre (///) in F#. I commenti XML possono precedere le dichiarazioni nei file di codice (con estensione fsi) o nei file di firma (fsi).

I commenti in formato documentazione XML sono commenti speciali, aggiunti alla definizione di ogni tipo o membro definito dall'utente. Sono speciali perché possono essere elaborati dal compilatore per generare un file di documentazione XML in fase di compilazione. Il file XML generato dal compilatore può essere distribuito insieme all'assembly .NET in modo che gli IDE possano usare le descrizioni comando per visualizzare informazioni rapide sui tipi o sui membri. Inoltre, il file XML può essere eseguito tramite strumenti come fsdocs per generare siti Web di riferimento api.

I commenti della documentazione XML, come tutti gli altri commenti, vengono ignorati dal compilatore, a meno che le opzioni descritte di seguito non siano abilitate per verificare la validità e la completezza dei commenti in fase di compilazione.

È possibile generare il file XML in fase di compilazione eseguendo una delle operazioni seguenti:

È possibile aggiungere un GenerateDocumentationFile elemento alla <PropertyGroup> sezione del file di .fsproj progetto, che genera un file XML nella directory del progetto con lo stesso nome file radice dell'assembly. Ad esempio:
```
<GenerateDocumentationFile>true</GenerateDocumentationFile>
```
Per altre informazioni, vedere La proprietà GenerateDocumentationFile.
Se si sviluppa un'applicazione tramite Visual Studio, fare clic con il pulsante destro del mouse sul progetto e scegliere Proprietà. Nella finestra di dialogo Proprietà selezionare la scheda Genera e controllare File di documentazione XML. È anche possibile modificare il percorso in cui il compilatore scrive il file.

Esistono due modi per scrivere commenti della documentazione XML: con e senza tag XML. Entrambi usano commenti a barra triplica.

Commenti senza tag XML

Se un /// commento non inizia con , <l'intero testo del commento viene preso come documentazione di riepilogo per il costrutto di codice che segue immediatamente. Utilizzare questo metodo quando si desidera scrivere solo un breve riepilogo per ogni costrutto.

Il commento viene codificato in XML durante la preparazione della documentazione, pertanto i caratteri come <, >e & non devono essere preceduti da caratteri di escape. Se non si specifica un tag di riepilogo in modo esplicito, non è consigliabile specificare altri tag, ad esempio param o restituisce tag.

Nell'esempio seguente viene illustrato il metodo alternativo, senza tag XML. In questo esempio l'intero testo nel commento viene considerato un riepilogo.

/// 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

Commenti con tag XML

Se un corpo del commento inizia con < (in genere <summary>), viene considerato come corpo di commento formattato XML usando tag XML. Questo secondo modo consente di specificare note separate per un breve riepilogo, osservazioni aggiuntive, documentazione per ogni parametro e parametro di tipo e eccezioni generate e una descrizione del valore restituito.

Di seguito è riportato un commento tipico della documentazione XML in un file di firma:

/// <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

Tag consigliati

Se si usano tag XML, nella tabella seguente vengono descritti i tag esterni riconosciuti nei commenti di codice XML F#.

Sintassi dei tag	Descrizione
`<summary>`*Testo*`</summary>`	Specifica che il testo è una breve descrizione dell'elemento del programma. La descrizione è in genere una o due frasi.
`<remarks>`*Testo*`</remarks>`	Specifica che il testo contiene informazioni supplementari sull'elemento program.
`<param name="`*nome`">`descrizione*`</param>`	Specifica il nome e la descrizione per un parametro di funzione o metodo.
`<typeparam name="`*nome`">`descrizione*`</typeparam>`	Specifica il nome e la descrizione per un parametro di tipo.
`<returns>`*Testo*`</returns>`	Specifica che il testo descrive il valore restituito di una funzione o di un metodo.
`<exception cref="`*Descrizione del tipo*`"></exception>`	Specifica il tipo di eccezione che può essere generata e le circostanze in cui viene generata.
`<seealso cref="`*reference*`"/>`	Specifica un collegamento Vedere anche alla documentazione per un altro tipo. Il riferimento è il nome visualizzato nel file della documentazione XML. Vedere Anche i collegamenti vengono visualizzati in genere nella parte inferiore di una pagina della documentazione.

Nella tabella seguente vengono descritti i tag da usare nelle sezioni di descrizione:

Sintassi dei tag	Descrizione
`<para>`*Testo*`</para>`	Specifica un paragrafo di testo. Viene utilizzato per separare il testo all'interno del tag osservazioni .
`<code>`*Testo*`</code>`	Specifica che il testo è costituito da più righe di codice. Questo tag può essere usato dai generatori di documentazione per visualizzare il testo in un tipo di carattere appropriato per il codice.
`<paramref name="`*name*`"/>`	Specifica un riferimento a un parametro nello stesso commento della documentazione.
`<typeparamref name="`*name*`"/>`	Specifica un riferimento a un parametro di tipo nello stesso commento della documentazione.
`<c>`*Testo*`</c>`	Specifica che il testo è codice inline. Questo tag può essere usato dai generatori di documentazione per visualizzare il testo in un tipo di carattere appropriato per il codice.
`<see cref="`*testo di riferimento*`"></see>`	Specifica un collegamento inline a un altro elemento del programma. Il riferimento è il nome visualizzato nel file della documentazione XML. Il testo è il testo visualizzato nel collegamento.

Tag definiti dall'utente

I tag precedenti rappresentano quelli riconosciuti dal compilatore F# e dagli strumenti tipici dell'editor F#. Gli utenti comunque possono definire tag personalizzati. Strumenti come fsdocs supportano tag aggiuntivi come <namespacedoc>. Gli strumenti di creazione della documentazione interna o personalizzata possono anche essere usati con i tag standard e con più formati di output da HTML a PDF.

Controllo in fase di compilazione

Quando --warnon:3390 è abilitato, il compilatore verifica la sintassi del codice XML e i parametri a cui si fa riferimento in <param> e <paramref> tag.

Documentazione di costrutti F#

I costrutti F# come moduli, membri, case di unione e campi di record sono documentati da un /// commento immediatamente prima della dichiarazione. Se necessario, i costruttori impliciti delle classi sono documentati assegnando un /// commento prima dell'elenco di argomenti. Ad esempio:

/// This is the type
type SomeType
      /// This is the implicit constructor
      (a: int, b: int) =

    /// This is the member
    member _.Sum() = a + b

Limiti

Alcune funzionalità della documentazione XML in C# e altri linguaggi .NET non sono supportate in F#.

In F#, i riferimenti incrociati devono usare la firma XML completa del simbolo corrispondente, ad esempio cref="T:System.Console". I semplici riferimenti incrociati in stile C#, cref="Console" ad esempio, non vengono elaborati in firme XML complete e questi elementi non vengono controllati dal compilatore F#. Alcuni strumenti di documentazione possono consentire l'uso di questi riferimenti incrociati tramite l'elaborazione successiva, ma è consigliabile usare le firme complete.
I tag <include>, <inheritdoc> non sono supportati dal compilatore F#. Non viene fornito alcun errore se vengono usati, ma vengono semplicemente copiati nel file di documentazione generato senza influire in caso contrario sulla documentazione generata.
I riferimenti incrociati non vengono controllati dal compilatore F#, anche quando -warnon:3390 vengono usati.
I nomi usati nei tag <typeparam> e <typeparamref> non vengono controllati dal compilatore F#, anche quando --warnon:3390 viene usato.
Non vengono visualizzati avvisi se la documentazione non è presente, anche quando --warnon:3390 viene usata.

Consigli

La documentazione del codice è consigliabile per vari motivi. Di seguito sono riportate alcune procedure consigliate, scenari di casi d'uso generali e aspetti da conoscere quando si usano tag di documentazione XML nel codice F#.

Abilitare l'opzione --warnon:3390 nel codice per assicurarsi che la documentazione XML sia xml valida.
Prendere in considerazione l'aggiunta di file di firma per separare i commenti della documentazione XML lunghi dall'implementazione.
Per mantenere una certa coerenza, tutti i tipi visibili pubblicamente e i loro membri devono essere documentati. Se necessario, è consigliabile eseguire un'operazione completa.
Al minimo, i moduli, i tipi e i relativi membri devono avere un commento o <summary> un tag normale///. Verrà visualizzata in una finestra della descrizione comando di completamento automatico negli strumenti di modifica F#.
Il testo della documentazione deve essere scritto usando frasi complete che terminano con un punto.

Share via