Kód dokumentálása XML-megjegyzésekkel

Cikk
03/12/2024

Az F#-ban három perjeles (///) kódbejegyzésekből készíthet dokumentációt. Az XML-megjegyzések megelőzhetik a kódfájlokban (.fs) vagy az aláírási (.fsi) fájlokban lévő deklarációkat.

Az XML-dokumentáció megjegyzései egy speciális megjegyzéstípus, amely a felhasználó által definiált típus vagy tag definíciója fölé kerül. Különlegesek, mert a fordító feldolgozhatja őket egy XML-dokumentációs fájl fordításkor történő létrehozásához. A fordító által létrehozott XML-fájl a .NET-szerelvény mellett terjeszthető, így az azonosítók elemleírásokkal jeleníthetik meg a típusok vagy tagok gyors információit. Emellett az XML-fájl futtatható olyan eszközökkel is, mint az fsdocs az API referenciawebhelyeinek létrehozásához.

Az XML-dokumentáció megjegyzéseit, mint minden más megjegyzést, a fordító figyelmen kívül hagyja, kivéve, ha az alábbi lehetőségek lehetővé teszik a megjegyzések érvényességének és teljességének ellenőrzését fordításkor.

Az XML-fájlt fordításkor az alábbiak egyikével hozhatja létre:

Hozzáadhat egy GenerateDocumentationFile elemet a <PropertyGroup> projektfájl szakaszához .fsproj , amely létrehoz egy XML-fájlt a projektkönyvtárban ugyanazzal a gyökérfájlnévvel, mint a szerelvény. Példa:
```
<GenerateDocumentationFile>true</GenerateDocumentationFile>
```
További információ: GenerateDocumentationFile tulajdonság.
Ha a Visual Studióval fejleszt alkalmazást, kattintson a jobb gombbal a projektre, és válassza a Tulajdonságok lehetőséget. A Tulajdonságok párbeszédpanelen válassza a Build lapot, és ellenőrizze az XML-dokumentációs fájlt. Azt is módosíthatja, hogy a fordító melyik helyre írja a fájlt.

Xml-dokumentációs megjegyzések írásának két módja van: XML-címkékkel és anélkül. Mindkettő három perjeles megjegyzést használ.

XML-címkék nélküli megjegyzések

Ha egy /// megjegyzés nem egy megjegyzéssel <kezdődik, akkor a rendszer a teljes megjegyzésszöveget veszi fel az azonnal következő kódszerkezet összefoglaló dokumentációjaként. Ezt a módszert akkor használja, ha csak egy rövid összefoglalást szeretne írni az egyes szerkezetekhez.

A megjegyzés xml-kódba van kódolva a dokumentáció előkészítése során, így az olyan karaktereket, mint <a , >és & nem kell feloldani. Ha nem ad meg explicit módon összefoglaló címkét, ne adjon meg más címkéket, például param vagy visszaadott címkéket.

Az alábbi példa az XML-címkék nélküli alternatív módszert mutatja be. Ebben a példában a megjegyzés teljes szövege összefoglalónak minősül.

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

XML-címkékkel ellátott megjegyzések

Ha egy megjegyzés törzse (általában<summary>) kezdetű < , akkor xml formátumú megjegyzéstörzsként kezeli a rendszer XML-címkékkel. Ez a második módszer lehetővé teszi, hogy külön jegyzeteket adjon meg egy rövid összefoglaláshoz, további megjegyzésekhez, az egyes paraméterek dokumentációihoz és a típusparaméterekhez és a kivételekhez, valamint a visszatérési érték leírásához.

Az alábbiakban egy jellemző XML-dokumentációs megjegyzés található egy aláírásfájlban:

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

Ajánlott címkék

HA XML-címkéket használ, az alábbi táblázat az F# XML-kód megjegyzéseiben felismert külső címkéket ismerteti.

Címkeszintaxis	Leírás
`<summary>`*text*`</summary>`	Azt adja meg, hogy a szöveg a programelem rövid leírása. A leírás általában egy vagy két mondat.
`<remarks>`*text*`</remarks>`	Megadja, hogy a szöveg kiegészítő információkat tartalmaz-e a programelemről.
`<param name="`*név`">`leírása*`</param>`	Egy függvény vagy metódusparaméter nevét és leírását adja meg.
`<typeparam name="`*név`">`leírása*`</typeparam>`	Megadja egy típusparaméter nevét és leírását.
`<returns>`*text*`</returns>`	Megadja, hogy a szöveg egy függvény vagy metódus visszatérési értékét írja le.
`<exception cref="`*típus`">`leírása*`</exception>`	Megadja a létrehozható kivétel típusát és azokat a körülményeket, amelyek miatt a kivételt ki lehet dobni.
`<seealso cref="`*Hivatkozás*`"/>`	Egy másik típus dokumentációjának Lásd még hivatkozását adja meg. A hivatkozás az XML-dokumentációs fájlban megjelenő név. Lásd: A dokumentációs oldal alján általában megjelennek a hivatkozások.

Az alábbi táblázat a leírási szakaszokban használható címkéket ismerteti:

Címkeszintaxis	Leírás
`<para>`*text*`</para>`	Szöveg bekezdését adja meg. Ez a megjegyzéscímkén belüli szöveg elválasztására szolgál.
`<code>`*text*`</code>`	Azt adja meg, hogy a szöveg több sornyi kód. Ezt a címkét a dokumentációkészítők használhatják a kódnak megfelelő betűtípusban lévő szöveg megjelenítéséhez.
`<paramref name="`*név*`"/>`	Egy paraméterre mutató hivatkozást ad meg ugyanabban a dokumentációs megjegyzésben.
`<typeparamref name="`*név*`"/>`	Egy típusparaméterre mutató hivatkozást ad meg ugyanabban a dokumentációs megjegyzésben.
`<c>`*text*`</c>`	Meghatározza, hogy a szöveg beágyazott kód-e. Ezt a címkét a dokumentációkészítők használhatják a kódnak megfelelő betűtípusban lévő szöveg megjelenítéséhez.
`<see cref="`*referenciaszöveg*`"></see>`	Egy másik programelemhez mutató beágyazott hivatkozást ad meg. A hivatkozás az XML-dokumentációs fájlban megjelenő név. A szöveg a hivatkozásban látható szöveg.

Felhasználó által definiált címkék

Az előző címkék az F#-fordító és a tipikus F# szerkesztőeszköz által felismert címkéket jelölik. A felhasználók azonban szabadon definiálhatják saját címkéiket. Az olyan eszközök, mint az fsdocs, támogatják az olyan további címkéket, mint a namespacedoc>.< A szabványos címkékkel egyéni vagy házon belüli dokumentációkészítési eszközök is használhatók, és a HTML-ről PDF-be több kimeneti formátum is támogatott.

Fordítási idő ellenőrzése

Ha --warnon:3390 engedélyezve van, a fordító ellenőrzi az XML szintaxisát, valamint a hivatkozott <param> paramétereket és <paramref> címkéket.

F#-szerkezetek dokumentálása

Az F#-szerkezeteket, például a modulokat, a tagokat, az egyesítő eseteket és a rekordmezőket közvetlenül a deklaráció előtt egy /// megjegyzés dokumentálja. Szükség esetén az osztályok implicit konstruktorait az argumentumlista előtt megjegyzés megadásával /// dokumentáljuk. Példa:

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

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

Korlátozások

A C# és más .NET-nyelvek XML-dokumentációjának egyes funkciói nem támogatottak az F#-ban.

Az F#-ban a kereszthivatkozásoknak például a megfelelő szimbólum teljes XML-aláírását cref="T:System.Console"kell használniuk. Egyszerű C#-stílusú kereszthivatkozások, például cref="Console" nem teljes XML-aláírásokra vannak kidolgozva, és ezeket az elemeket az F#-fordító nem ellenőrzi. Egyes dokumentációs eszközök lehetővé tehetik a kereszthivatkozások későbbi feldolgozással történő használatát, de a teljes aláírást használni kell.
A címkéket <include><inheritdoc> az F# fordító nem támogatja. Nem jelenik meg hiba a használatukkor, de a rendszer egyszerűen átmásolja őket a létrehozott dokumentációs fájlba anélkül, hogy más módon befolyásolná a létrehozott dokumentációt.
Az F#-fordító nem ellenőrzi a kereszthivatkozásokat, még akkor sem, ha -warnon:3390 használatban van.
A címkékben <typeparam><typeparamref> használt neveket az F#-fordító nem ellenőrzi, még akkor sem, ha --warnon:3390 használják.
Nem kap figyelmeztetést, ha a dokumentáció hiányzik, még akkor sem, ha --warnon:3390 használatban van.

Ajánlások

A kód dokumentálása számos okból ajánlott. Az alábbiakban bemutatunk néhány ajánlott eljárást, általános használati esetet, valamint azokat a tudnivalókat, amelyeket az XML-dokumentáció címkéinek F#-kódban való használatakor érdemes tudnia.

Engedélyezze a kódban található beállítást --warnon:3390 , hogy meggyőződjön arról, hogy az XML-dokumentáció érvényes XML-fájl.
Fontolja meg aláírásfájlok hozzáadását, hogy elkülönítse a hosszú XML-dokumentáció megjegyzéseit a megvalósítástól.
A konzisztencia érdekében minden nyilvánosan látható típust és azok tagjait dokumentálni kell. Ha meg kell tennie, tegye meg az egészet.
Minimális szinten a moduloknak, típusoknak és tagjaiknak egyszerű /// megjegyzéssel vagy <summary> címkével kell rendelkezniük. Ez egy automatikus kiegészítési elemleírás ablakban jelenik meg az F#-szerkesztőeszközökben.
A dokumentáció szövegét teljes mondatokkal kell megírni.