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

  • Makale

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.

Not

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>Çıktısı 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.

Belge oluşturmayı etkinleştirmek için projenizin özelliklerinin Derleme>Çıktısı bölümünde XML belge dosyası 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, alternatif bir konum girin veya bu konuma göz atın.

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

Kendi başına veya GenerateDocumentationFile özelliği olarak trueayarlanmış olarak kullanıyorsanızDocumentationFile, belirtilen ada ve konuma sahip bir belge dosyası oluşturulur. Ancak, olarak ayarlarsanız, özelliğini ayarlasanız GenerateDocumentationFile falsebile hiçbir belge dosyası oluşturulmaz DocumentationFile .

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

C# veya ''' Visual Basic'e 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# veya ''' Visual Basic yazın.
    • Düzenle menü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 öğesini, parametresi için bir <param> öğeyi ve dönüş değerini belgeleyen bir <returns> öğe oluşturur<summary>.

    /// <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 tıklanabilir cref veya href 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