Jak: použití funkcí dokumentace XML (Příručka programování C#)

Následující příklad obsahuje základní přehled typu byly dokumentovány.

Příklad

// If compiling from the command line, compile with: /doc:YourFileName.xml

/// <summary>
/// Class level summary documentation goes here.</summary>
/// <remarks>
/// Longer comments can be associated with a type or member through
/// the remarks tag.</remarks>
public class TestClass : TestInterface
{
    /// <summary>
    /// Store for the name property.</summary>
    private string _name = null;

    /// <summary>
    /// The class constructor. </summary>
    public TestClass()
    {
        // TODO: Add Constructor Logic here.
    }

    /// <summary>
    /// Name property. </summary>
    /// <value>
    /// A value tag is used to describe the property value.</value>
    public string Name
    {
        get
        {
            if (_name == null)
            {
                throw new System.Exception("Name is null");
            }
            return _name;
        }
    }

    /// <summary>
    /// Description for SomeMethod.</summary>
    /// <param name="s"> Parameter description for s goes here.</param>
    /// <seealso cref="System.String">
    /// You can use the cref attribute on any tag to reference a type or member 
    /// and the compiler will check that the reference exists. </seealso>
    public void SomeMethod(string s)
    {
    }

    /// <summary>
    /// Some other method. </summary>
    /// <returns>
    /// Return results are described through the returns tag.</returns>
    /// <seealso cref="SomeMethod(string)">
    /// Notice the use of the cref attribute to reference a specific method. </seealso>
    public int SomeOtherMethod()
    {
        return 0;
    }

    public int InterfaceMethod(int n)
    {
        return n * n;
    }

    /// <summary>
    /// The entry point for the application.
    /// </summary>
    /// <param name="args"> A list of command line arguments.</param>
    static int Main(System.String[] args)
    {
        // TODO: Add code to start application here.
        return 0;
    }
}

/// <summary>
/// Documentation that describes the interface goes here.
/// </summary>
/// <remarks>
/// Details about the interface go here.
/// </remarks>
interface TestInterface
{
    /// <summary>
    /// Documentation that describes the method goes here.
    /// </summary>
    /// <param name="n">
    /// Parameter n requires an integer argument.
    /// </param>
    /// <returns>
    /// The method returns an integer.
    /// </returns>
    int InterfaceMethod(int n);
}

Probíhá kompilace kódu

Kompilace v příkladu, zadejte následující příkaz:

csc XMLsample.cs /doc:XMLsample.xml

Tím se vytvoří soubor XMLsample.xml, který lze zobrazit v prohlížeči, nebo pomocí příkazu typu XML.

Robustní programování

Dokumentace XML začíná / / /.Při vytvoření nového projektu do průvodců některé starter / / / řádky.Zpracování těchto poznámek má některá omezení:

• Dokumentace musí být ve správném formátu XML.Pokud není ve správném formátu XML, je generována upozornění a soubor dokumentace bude obsahovat komentář, který říká, že došlo k chybě.

• Vývojáři mohou vytvořit vlastní sadu tagů.Je doporučeno sadou tagů (viz část další čtení).Některé doporučené značky mají speciální význam:

  • <param> značka se používá k popisu parametrů.Pokud, kompilátor bude ověřovat, že parametr existuje a že všechny parametry jsou popsány v dokumentaci.Ověření se nezdařilo, vydá varování kompilátoru.

  • cref Atribut lze připojit k libovolné značky poskytnout odkaz na element kódu.Kompilátor bude ověřte, zda existuje tento prvek kódu.Ověření se nezdařilo, vydá varování kompilátoru.Kompilátor respektuje všechny using prohlášení při typu popsaného v cref atributu.

  • <summary> technologie IntelliSense uvnitř Visual Studio používá značku zobrazíte další informace o typu nebo člen.

    [!POZNÁMKA]

    Soubor XML neposkytuje úplné informace o typu a členy (například neobsahuje žádné informace o typu).Chcete-li získat úplné informace o typu nebo člen musí použití souboru dokumentace společně s odraz na skutečný typ nebo člen.

Viz také

Referenční dokumentace

/doc (Možnosti C# kompilátoru)

Komentáře XML dokumentace (Příručka programování C#)

Koncepty

Příručka programování C#