Aracılığıyla paylaş

Belge oluşturma için XML açıklamaları ekleme

Bu makalede Visual Studio'nun standart XML belge açıklama yapısını otomatik olarak oluşturarak sınıflar ve yöntemler gibi kod öğelerini belgelemenize nasıl yardımcı olabileceği açıklanır. Derleme zamanında, belge açıklamalarını içeren bir XML dosyası oluşturabilirsiniz.

Visual Studio ve diğer IDE'ler, türler ve üyeler hakkında hızlı bilgi göstermek için IntelliSense'i kullanabilmesi için derleyici tarafından oluşturulan XML dosyasını .NET derlemenizle birlikte dağıtabilirsiniz. XML dosyasını DocFX ve Sandcastle gibi araçlar aracılığıyla çalıştırarak API başvuru web siteleri de oluşturabilirsiniz.

Uyarı

XML belgelerinin açıklama yapısını otomatik olarak eklemek için Açıklama Ekle komutu C# ve Visual Basic'te kullanılabilir. C++ için , XML belge açıklamalarını el ile ekleyebilir ve derleme zamanında XML belge dosyaları oluşturmaya devam edebilirsiniz.

Belge oluşturmayı etkinleştirme

Belge oluşturmayı etkinleştirmek için projenizin özelliklerinin Derleme> sekmesinde API belgeleri içeren bir dosya oluştur onay kutusunu seçin.

Varsayılan olarak, .xml dosya uzantısına sahip derlemenizle aynı adlı bir belge dosyası, derlemeyle aynı dizinde oluşturulur. Dosya için bilinmeyen bir ad veya konum yapılandırmak istiyorsanız , XML belgeleri dosya yolu altında alternatif bir konum girin veya bu konuma göz atın.

Alternatif olarak, GenerateDocumentationFile veya DocumentationFile özelliklerini .csproj, .vbproj veya .fsproj dosyanıza ekleyebilirsiniz. "GenerateDocumentationFile bir belge dosyası oluşturmak için varsayılan ad ve konuma true olarak ayarlayın." DocumentationFile Farklı bir ad veya konum belirtmek için özelliğini kullanın.

DocumentationFile kendi başına veya GenerateDocumentationFile özelliği true olacak şekilde ayarlandığında kullanırsanız, belirtilen ada ve konuma sahip bir belge dosyası oluşturulur. Ancak, GenerateDocumentationFile'u false olarak ayarlarsanız, DocumentationFile özelliğini ayarlasanız bile hiçbir belge dosyası oluşturulmaz.

Açıklama ekleme klavye kısayolu etkinleştir

C# veya Visual Basic'te /// yazdıktan sonra, Açıklamalar seçeneğini XML açıklama yapılarını otomatik olarak eklemek için ayarlayabilirsiniz.

  1. Visual Studio menü çubuğundan Araçlar>Seçenekleri'ni seçin.
  2. Seçenekler iletişim kutusunda Metin Düzenleyicisi>C# (veya Visual Basic) >Gelişmiş'e gidin.
  3. Açıklamalar bölümünde\\\ için XML belgeleri açıklamaları oluştur (veya ''') öğesini seçin veya seçimini kaldırın.

XML açıklamasını otomatik olarak ekleme

  1. Visual Studio'da imlecinizi belgelamak istediğiniz öğenin üzerine getirin, örneğin bir yöntem.

  2. Aşağıdaki eylemlerden birini uygulayın:

    • Otomatik açıklama ekleme kısayolu etkinse, C# için /// veya Visual Basic için ''' yazın.
    • Düzenlemenüsünden IntelliSense>Açıklama Ekle'yi seçin.
    • Sağ tıklama veya bağlam menüsünden Kod Parçacığı>Açıklama Ekle'yi seçin.

    XML açıklama yapısı hemen kod öğesinin üzerinde oluşturulur. Örneğin, aşağıdaki GetUserName yönteme açıklama eklerken, şablon <summary> öğesini, parametre için bir <param> öğesini ve dönüş değerini belgelemek için bir <returns> öğesini oluşturur.

    /// <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. Kodu tam olarak belgeleme amacıyla her XML öğesinin açıklamalarını girin. Örneğin:

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

Kodun üzerine geldiğinizde Hızlı Bilgi'de işlenen açıklamalarda XML öğelerini ve stillerini kullanabilirsiniz. Bu öğeler, italik veya kalın stiller, madde işaretli veya numaralandırılmış listeler ve cref veya href gibi tıklanabilir bağlantılardır.

Örneğin, C# program dosyasına aşağıdaki kodu girin:

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

GetUserName öğesinin üzerine geldiğinizde Hızlı Bilgi bölmesi aşağıdaki gibi görünür:

Tıklanabilir bağlantı, numaralandırılmış liste ve italik ve kalın biçimlendirme için stil etiketleriyle tamamlanmış açıklamayı gösteren ekran görüntüsü.

İlgili içerik

  • Last updated on