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

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 generált XML-fájl a .NET assembly mellett terjeszthető, így az IDE-k felhasználhatják a tooltip funkciókat, hogy gyors tájékoztatást nyújtsanak a típusokról vagy tagokról. Emellett az XML-fájl olyan eszközökkel is futtatható, mint az fsdocs API referenciawebhelyeinek létrehozásához.

Alapértelmezés szerint a fordító figyelmen kívül hagyja az XML-dokumentáció megjegyzéseit. Ennek módosításához állítsa be a --warnon:3390. A fordító ezután ellenőrzi az XML szintaxisát, valamint a <param> és <paramref> címkékben említett paramétereket.

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

• Hozzáadhat egy GenerateDocumentationFile elemet a .fsproj projektfájl <PropertyGroup> szakaszához, amely létrehoz egy XML-fájlt a projektkönyvtárban, amelynek gyökérfájlneve megegyezik a szerelvény nevével. Például:

  <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ágoklehetőséget. A Tulajdonságok párbeszédpanelen válassza a Build lapot, és jelölje be a XML-dokumentációs fájl. 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 <-gyel kezdődik, akkor a teljes megjegyzésszöveg tekinthető 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 <, >é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 címkéket ad vissza.

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éstörzs < (általában <summary>) kezdődik, 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.

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

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 <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ő alatti ellenőrzés

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

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éldául:

/// 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 a megfelelő szimbólum teljes XML-aláírását kell használniuk, például cref="T:System.Console". Az egyszerű C#-stílusú kereszthivatkozások, például a 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.

• Az F# fordító nem támogatja a címkéket <include>, <inheritdoc>. 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ál.

• A címkékben <typeparam> és <typeparamref> használt neveket az F#-fordító még akkor sem ellenőrzi, ha --warnon:3390 van használatban.

• Nem kap figyelmeztetést, ha a dokumentáció hiányzik, még akkor sem, ha --warnon:3390 használ.

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 --warnon:3390 beállítást, 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 már meg kell tennie, csinálja meg teljesen.

• 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 ablakban jelenik meg az F#-szerkesztőeszközökben.

• A dokumentáció szövegét teljes mondatokkal kell megírni, amelyek ponttal végződnek.

Lásd még:

• C# XML dokumentációs megjegyzései (C# programozási útmutató).
• F# nyelvi referencia
• Fordító beállításai