Porady: użycie funkcji dokumentacji XML (Przewodnik programowania w języku C#)

Poniższy przykład zawiera omówienie podstawowych typu, które zostały udokumentowane.

Przykład

// 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);
}

Kompilowanie kodu

Aby skompilować w przykładzie, wpisz następujący wiersz polecenia:

csc XMLsample.cs /doc:XMLsample.xml

Spowoduje to utworzenie pliku XML XMLsample.xml, który można wyświetlić w przeglądarce lub korzystając z polecenia typu.

Stabilne programowanie

Plik dokumentacji XML rozpoczyna się od / / /.Podczas tworzenia nowego projektu kreatorów wprowadzone niektóre starter / / / linie w.Przetwarzanie tych uwag ma pewne ograniczenia:

• Dokumentacja musi być poprawnie sformułowany kod XML.Jeśli kod XML nie jest poprawnie sformułowanym, jest generowane ostrzeżenie i dokumentacji pliku będzie zawierać komentarz, który mówi, że wystąpił błąd.

• Deweloperzy mają swobodę tworzenia własnego zestawu tagów.Istnieje zalecany zestaw znaczników (patrz sekcja dalszego czytania).Niektóre znaczniki zalecane mają specjalne znaczenie:

  • <param> Tag jest używany do opisu parametrów.Używane, kompilator będzie sprawdzać, czy parametr istnieje i że wszystkie parametry są opisane w dokumentacji.Jeśli nie można zweryfikować, kompilator generuje ostrzeżenie.

  • cref Atrybut może zostać dołączony do dowolny znacznik, aby podać odwołanie do elementu kodu.Kompilator będzie sprawdzać, czy istnieje element ten kod.Jeśli nie można zweryfikować, kompilator generuje ostrzeżenie.Kompilator uwzględnia dowolne using instrukcji, gdy szuka typu opisanego w cref atrybut.

  • <summary> Tag jest używany przez technologię IntelliSense wewnątrz programu Visual Studio, aby wyświetlić dodatkowe informacje dotyczące typu lub członka.

    [!UWAGA]

    Plik XML nie zapewnia pełną informację o rodzaju i członków (na przykład go nie zawiera żadnych informacji o typie).Aby uzyskać pełne informacje dotyczące typu lub członka, plik dokumentacji musi być używany razem z rozważania na temat rzeczywistego typu lub członka.

Zobacz też

Informacje

/doc (opcje kompilatora C#)

Komentarze dokumentacji XML (Przewodnik programowania w języku C#)

Koncepcje

Przewodnik programowania w języku C#