Megosztás:

XML-megjegyzések beszúrása a dokumentáció létrehozásához

Ez a cikk azt ismerteti, hogyan segíthet a Visual Studio a kódelemek, például osztályok és metódusok dokumentálásában a szabványos XML-dokumentáció megjegyzésstruktúra automatikus létrehozásával. Fordításkor létrehozhat egy XML-fájlt, amely tartalmazza a dokumentáció megjegyzéseit.

A fordító által létrehozott XML-fájlt a .NET-szerelvénysel együtt terjesztheti, így a Visual Studio és más azonosítók az IntelliSense használatával gyors információkat jeleníthetnek meg a típusokról és tagokról. Az XML-fájlt olyan eszközökkel is futtathatja, mint a DocFX és a Sandcastle , amelyek API-referenciawebhelyeket hoznak létre.

Megjegyzés:

Az XML-dokumentáció megjegyzésstruktúra automatikus beszúrásához használható Megjegyzés beszúrása parancs a C# és a Visual Basic alkalmazásban érhető el. C++ esetén manuálisan is beszúrhat XML-dokumentációs megjegyzéseket , és fordításkor is létrehozhat XML-dokumentációs fájlokat.

Dokumentáció létrehozásának engedélyezése

A dokumentáció létrehozásának engedélyezéséhez jelölje be az API-dokumentációt tartalmazó fájl létrehozása jelölőnégyzetet a projekt tulajdonságainak Build>Output lapján.

Alapértelmezés szerint a dokumentációs fájl, amely az összeállítással megegyező nevű és egy .xml fájlkiterjesztéssel rendelkezik, ugyanabban a könyvtárban jön létre, mint az összeállítás. Ha a fájlnak nem alapértelmezett nevet vagy helyet szeretne konfigurálni, adja meg vagy keresse meg az alternatív helyet az XML dokumentációs fájl elérési útjában.

Másik lehetőségként hozzáadhatja a GenerateDocumentationFile vagy a DocumentationFile tulajdonságokat a .csproj, .vbproj vagy .fsproj fájlhoz . Állítsa be GenerateDocumentationFile úgy, hogy true létrehoz egy dokumentációs fájlt az alapértelmezett névvel és hellyel. DocumentationFile A tulajdonság használatával adjon meg egy másik nevet vagy helyet.

Ha a DocumentationFile önmagában vagy úgy van beállítva, hogy a GenerateDocumentationFile tulajdonság true legyen, a rendszer létrehoz egy dokumentációs fájlt a megadott névvel és helyen. Ha azonban a GenerateDocumentationFile be van állítva a false értékre, akkor sem keletkezik dokumentációs fájl, még ha a DocumentationFile tulajdonságot be is állítja.

A megjegyzés beszúrására szolgáló billentyűparancs engedélyezése

A Megjegyzések beállítással automatikusan beszúrhat XML-megjegyzésstruktúrákat, miután beírja a /// a C#-ban vagy a ''' a Visual Basicben.

  1. A Visual Studio menüsávon válassza az Eszközök>Beállításoklehetőséget.
  2. A Beállítások párbeszédpanelen navigáljon a Szövegszerkesztő>C# (vagy Visual Basic) >Speciális menüpontra.
  3. A Megjegyzések szakaszban válassza ki vagy törölje a jelölést az XML-dokumentáció megjegyzéseinek létrehozása a következőhöz: \\\ (vagy '').

XML-megjegyzés automatikus beszúrása

  1. A Visual Studióban helyezze a kurzort a dokumentálni kívánt elem fölé, például egy metódusra.

  2. Válasszon a következő lehetőségek közül:

    • Ha az automatikus megjegyzésbeszúrási parancsikon engedélyezve van, írja be /// a C#-be vagy ''' a Visual Basicbe.
    • A Szerkesztés menüben válassza az IntelliSense>Megjegyzés beszúrása lehetőséget.
    • A jobb gombbal vagy a helyi menüben válassza aKódrészlet>Megjegyzés beszúrása.

    Az XML-megjegyzésstruktúra azonnal létre lesz hozva a kódelem felett. Ha például megjegyzést fűz a következő GetUserName metódushoz, a sablon létrehozza az <summary> elemet, a paraméter egy <param> elemét, és egy <returns> elemet a visszatérési érték dokumentálásához.

    /// <summary>
/// 
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
public string GetUserName(int id)
{
    return "username";
}

    ''' <summary>
''' 
''' </summary>
''' <param name="id"></param>
''' <returns></returns>
Public Function GetUserName(id As Integer) As String
    Return "username"
End Function

  3. Adja meg az egyes XML-elemek leírását a kód teljes dokumentálásához. Például:

     /// <summary>
 /// Gets the username associated with the specified ID.
 /// </summary>
 /// <param name="id">The unique user ID.</param>
 /// <returns>A string containing the username for the specified ID.</returns>
 public string GetUserName(int id)
 {
     return "username";
 }

Xml-elemeket és stílusokat használhat olyan megjegyzésekben, amelyek a gyors információban jelennek meg, amikor a kód fölé viszi az egérmutatót. Ezek közé tartoznak a dőlt vagy félkövér stílusok, a felsorolás- vagy számozott listák, valamint a kattintható cref vagy href hivatkozások.

Írja be például a következő kódot egy C#-programfájlba:

/// <summary>
/// There are two <see href="https://bing.com">params</see>.
/// <list type="number">
/// <item><param name="id">The user <em>id</em></param></item>
/// <item><param name="username">The user <em>name</em></param></item>
/// </list>
/// </summary>
/// <returns>The <strong>username</strong>.</returns>
public static string GetUserName(int id)
{
    return "username";
}

Amikor a GetUserName fölé viszi az egérmutatót, a Gyors információ panel a következőképpen jelenik meg:

Képernyőkép a kész megjegyzésről, amely stíluscímkéket tartalmaz egy kattintható hivatkozáshoz, egy számozott listához, valamint dőlt és félkövér formázáshoz.

Kapcsolódó tartalom

  • Last updated on