C# Language
XML Documentation Comments

Opmerkingen

Eenvoudige methode-annotatie

Documentatiereacties worden direct boven de methode of klasse die ze beschrijven geplaatst. Ze beginnen met drie schuine strepen /// en kunnen meta-informatie worden opgeslagen via XML.

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

Informatie binnen de tags kan worden gebruikt door Visual Studio en andere hulpmiddelen om diensten zoals IntelliSense te leveren:

Zie ook de lijst met veelgebruikte documentatie-tags van Microsoft .

Opmerkingen over de interface en klassedocumentatie

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

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

Resultaat

Interface samenvatting

Klasse samenvatting

Methodedocumentatiecommentaar met param- en retourelementen

/// <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 toont u de beschrijving voor elke parameter:

Tip: als Intellisense niet wordt weergegeven in Visual Studio, verwijdert u de eerste haakje of komma en typt u deze opnieuw.

XML genereren op basis van documentatie-opmerkingen

Om een XML-documentatiebestand te genereren op basis van documentatie-opmerkingen in de code, gebruikt u de optie /doc met de csc.exe C # compiler.

Schakel in Visual Studio 2013/2015 in Project -> Eigenschappen -> Build -> Output het selectievakje XML documentation file :

Wanneer u het project bouwt, wordt een XML-bestand door de compiler geproduceerd met een naam die overeenkomt met de projectnaam (bijvoorbeeld XMLDocumentation.dll -> XMLDocumentation.xml ).

Wanneer u de assembly in een ander project gebruikt, moet u ervoor zorgen dat het XML-bestand zich in dezelfde map bevindt als de DLL waarnaar wordt verwezen.

Dit voorbeeld:

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

Produceert deze XML bij het bouwen:

<?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>

Verwijzen naar een andere klasse in documentatie

De tag <see> kan worden gebruikt om naar een andere klasse te linken. Het bevat het cref lid dat de naam van de klasse moet bevatten waarnaar moet worden verwezen. Visual Studio biedt Intellsense bij het schrijven van deze tag en dergelijke verwijzingen worden ook verwerkt bij het hernoemen van de klasse waarnaar wordt verwezen.

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

In Visual Studio Intellisense-pop-ups worden dergelijke verwijzingen ook gekleurd in de tekst weergegeven.

Om naar een generieke klasse te verwijzen, gebruikt u iets dat lijkt op het volgende:

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