C# Language
XML-dokumentation Kommentarer

Anmärkningar

Enkel metodanteckning

Dokumentationskommentarer placeras direkt ovanför metoden eller klassen som de beskriver. De börjar med tre snedstreck /// och gör det möjligt att lagra metainformation via XML.

/// <summary>
/// Bar method description
/// </summary>
public void Bar()
{ 
        
}

Information inuti taggarna kan användas av Visual Studio och andra verktyg för att tillhandahålla tjänster som IntelliSense:

Se även Microsofts lista över vanliga dokumentationstaggar .

Kommentarer om gränssnitt och klassdokumentation

/// <summary>
/// This interface can do Foo
/// </summary>
public interface ICanDoFoo
{
    // ... 
}

/// <summary>
/// This Bar class implements ICanDoFoo interface
/// </summary>
public class Bar : ICanDoFoo
{
    // ...
}

Resultat

Gränssnittsöversikt

Klassöversikt

Metoddokumentation kommenterar med param och returnerar element

/// <summary>
/// Returns the data for the specified ID and timestamp.
/// </summary>
/// <param name="id">The ID for which to get data. </param>
/// <param name="time">The DateTime for which to get data. </param>
/// <returns>A DataClass instance with the result. </returns>
public DataClass GetData(int id, DateTime time)
{
   // ...
}

IntelliSense visar beskrivningen för varje parameter:

Tips: Om Intellisense inte visas i Visual Studio, ta bort den första konsolen eller komma och skriv den sedan igen.

Genererar XML från dokumentationskommentarer

För att generera en XML-dokumentationsfil från dokumentationskommentarer i koden, använd alternativet /doc med csc.exe C # -kompileraren.

I Visual Studio 2013/2015, I projekt -> Egenskaper -> Bygg -> Output , markera kryssrutan för XML documentation file :

När du bygger projektet kommer en XML-fil att produceras av kompilatorn med ett namn som motsvarar projektnamnet (t.ex. XMLDocumentation.dll -> XMLDocumentation.xml ).

När du använder enheten i ett annat projekt, se till att XML-filen finns i samma katalog som det refereras till i DLL-filen.

Detta exempel:

/// <summary>
/// Data class description
/// </summary>
public class DataClass
{
    /// <summary>
    /// Name property description
    /// </summary>
    public string Name { get; set; }
}


/// <summary>
/// Foo function
/// </summary>
public class Foo
{
    /// <summary>
    /// This method returning some data
    /// </summary>
    /// <param name="id">Id parameter</param>
    /// <param name="time">Time parameter</param>
    /// <returns>Data will be returned</returns>
    public DataClass GetData(int id, DateTime time)
    {
        return new DataClass();
    }
}

Producerar denna xml vid build:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>XMLDocumentation</name>
    </assembly>
    <members>
        <member name="T:XMLDocumentation.DataClass">
            <summary>
            Data class description
            </summary>
        </member>
        <member name="P:XMLDocumentation.DataClass.Name">
            <summary>
            Name property description
            </summary>
        </member>
        <member name="T:XMLDocumentation.Foo">
            <summary>
            Foo function
            </summary>
        </member>
        <member name="M:XMLDocumentation.Foo.GetData(System.Int32,System.DateTime)">
            <summary>
            This method returning some data
            </summary>
            <param name="id">Id parameter</param>
            <param name="time">Time parameter</param>
            <returns>Data will be returned</returns>
        </member>
    </members>
</doc>

Referera till en annan klass i dokumentation

Taggen <see> kan användas för att länka till en annan klass. Den innehåller cref medlemmen som ska innehålla namnet på klassen som ska refereras. Visual Studio kommer att tillhandahålla Intellsense när du skriver denna tagg och sådana referenser kommer att behandlas när man också byter namn på den refererade klassen.

/// <summary>
/// You might also want to check out <see cref="SomeOtherClass"/>.
/// </summary>
public class SomeClass
{
}

I Visual Studio Intellisense popups kommer sådana referenser också att visas färgade i texten.

Om du vill referera till en generisk klass använder du något som liknar följande:

/// <summary>
/// An enhanced version of <see cref="List{T}"/>.
/// </summary>
public class SomeGenericClass<T>
{
}