Kodunuzu XML açıklamaları ile belgele

  • Makale

F# dilinde üçlü eğik çizgi (///) kod açıklamalarından belge oluşturabilirsiniz. XML açıklamaları, kod dosyaları (.fs) veya imza (.fsi) dosyalarındaki bildirimlerin önüne gelebilir.

XML belge açıklamaları, kullanıcı tanımlı herhangi bir türün veya üyenin tanımının üzerine eklenen özel bir açıklama türüdür. Derleme zamanında bir XML belge dosyası oluşturmak için derleyici tarafından işlenebildiği için özeldirler. Derleyici tarafından oluşturulan XML dosyası.NET derlemenizle birlikte dağıtılabilir, böylece IDE'ler türler veya üyeler hakkında hızlı bilgileri göstermek için araç ipuçlarını kullanabilir. Ayrıca XML dosyası, API başvuru web siteleri oluşturmak için fsdocs gibi araçlar aracılığıyla çalıştırılabilir.

Derleme zamanında açıklamaların geçerliliğini ve eksiksizliğini denetlemek için aşağıda açıklanan seçenekler etkinleştirilmediği sürece, diğer tüm açıklamalar gibi XML belge açıklamaları derleyici tarafından yoksayılır.

Xml dosyasını derleme zamanında aşağıdakilerden birini yaparak oluşturabilirsiniz:

  • Proje dosyanızın .fsproj bölümüne, GenerateDocumentationFile proje dizininde derlemeyle aynı kök dosya adına sahip bir XML dosyası oluşturan bir öğe <PropertyGroup> ekleyebilirsiniz. Örneğin:

    <GenerateDocumentationFile>true</GenerateDocumentationFile>

    Daha fazla bilgi için bkz . GenerateDocumentationFile özelliği.

  • Visual Studio kullanarak uygulama geliştiriyorsanız projeye sağ tıklayın ve Özellikler'i seçin. Özellikler iletişim kutusunda Oluştur sekmesini seçin ve XML belge dosyasını denetleyin. Derleyicinin dosyayı yazdığı konumu da değiştirebilirsiniz.

XML belgeleri açıklamaları yazmanın iki yolu vardır: XML etiketleriyle ve xml etiketleri olmadan. Her ikisi de üçlü eğik çizgi açıklamaları kullanır.

XML etiketleri olmayan açıklamalar

Bir /// açıklama ile <başlamıyorsa, açıklama metninin tamamı hemen izleyen kod yapısının özet belgeleri olarak alınır. Her yapı için yalnızca kısa bir özet yazmak istediğinizde bu yöntemi kullanın.

Açıklama, belge hazırlama sırasında XML olarak kodlanır, bu nedenle , >ve & gibi <karakterlerin kaçışa gerek yoktur. Açıkça bir özet etiketi belirtmezseniz, param veya dönüş etiketleri gibi başka etiketler belirtmemelisiniz.

Aşağıdaki örnekte XML etiketleri olmadan alternatif yöntem gösterilmektedir. Bu örnekte, açıklamadaki metnin tamamı özet olarak kabul edilir.

/// Creates a new string whose characters are the result of applying
/// the function mapping to each of the characters of the input string
/// and concatenating the resulting strings.
val collect : (char -> string) -> string -> string

XML etiketleri içeren açıklamalar

Açıklama gövdesi ile < başlıyorsa (normalde <summary>), XML etiketleri kullanılarak XML biçimlendirilmiş bir açıklama gövdesi olarak değerlendirilir. Bu ikinci yöntem, kısa bir özet için ayrı notlar, ek açıklamalar, her parametre ve tür parametresi ve özel durumlar için belgeler ve döndürülen değerin açıklamasını belirtmenizi sağlar.

Aşağıda, imza dosyasındaki tipik bir XML belgeleri açıklaması verilmiştir:

/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each of the characters of the input string and concatenating the resulting
/// strings.</summary>
/// <param name="mapping">The function to produce a string from each character of the input string.</param>
///<param name="str">The input string.</param>
///<returns>The concatenated string.</returns>
///<exception cref="System.ArgumentNullException">Thrown when the input string is null.</exception>
val collect : (char -> string) -> string -> string

XML etiketleri kullanıyorsanız, aşağıdaki tabloda F# XML kod açıklamalarında tanınan dış etiketler açıklanmaktadır.

Etiket söz dizimi Açıklama
<summary>text</summary> Metnin program öğesinin kısa bir açıklaması olduğunu belirtir. Açıklama genellikle bir veya iki cümledir.
<remarks>text</remarks> Metnin program öğesi hakkında ek bilgiler içerdiğini belirtir.
<param name="ad">açıklaması</param> İşlev veya yöntem parametresinin adını ve açıklamasını belirtir.
<typeparam name="ad">açıklaması</typeparam> Tür parametresinin adını ve açıklamasını belirtir.
<returns>text</returns> Metnin bir işlevin veya yöntemin dönüş değerini açıklandığını belirtir.
<exception cref="tür">açıklaması</exception> Oluşturulabilecek özel durum türünü ve oluşturulduğu koşulları belirtir.
<seealso cref="Başvuru"/> Başka bir tür için belgelere yönelik Ayrıca Bkz. bağlantısını belirtir. Başvuru, XML belge dosyasında göründüğü şekilde addır. Ayrıca bkz. Bağlantılar genellikle belge sayfasının en altında görünür.

Aşağıdaki tabloda, açıklama bölümlerinin içinde kullanılacak etiketler açıklanmaktadır:

Etiket söz dizimi Açıklama
<para>text</para> Metin paragrafını belirtir. Bu, açıklamalar etiketinin içindeki metni ayırmak için kullanılır.
<code>text</code> Metnin birden çok kod satırı olduğunu belirtir. Bu etiket, metinleri koda uygun bir yazı tipinde görüntülemek için belge oluşturucuları tarafından kullanılabilir.
<paramref name="Adı"/> Aynı belge açıklamasında bir parametreye başvuru belirtir.
<typeparamref name="Adı"/> Aynı belge açıklamasında tür parametresine başvuru belirtir.
<c>text</c> Metnin satır içi kod olduğunu belirtir. Bu etiket, metinleri koda uygun bir yazı tipinde görüntülemek için belge oluşturucuları tarafından kullanılabilir.
<see cref="başvuru">metni</see> Başka bir program öğesine satır içi bağlantı belirtir. Başvuru, XML belge dosyasında göründüğü şekilde addır. Metin, bağlantıda gösterilen metindir.

Kullanıcı tanımlı etiketler

Önceki etiketler, F# derleyicisi ve tipik F# düzenleyici araçları tarafından tanınanları temsil ediyor. Ancak, bir kullanıcı kendi etiketlerini tanımlamakta serbesttir. fsdocs gibi araçlar, namespacedoc> gibi <ek etiketler için destek getirir. Özel veya şirket içi belge oluşturma araçları standart etiketlerle de kullanılabilir ve HTML'den PDF'ye birden çok çıkış biçimi desteklenebilir.

Derleme zamanı denetimi

Etkinleştirildiğinde --warnon:3390 , derleyici XML söz dizimini ve ve etiketlerinde <param><paramref> başvuruda bulunılan parametreleri doğrular.

F# Yapılarını Belgeleme

Modüller, üyeler, birleşim durumları ve kayıt alanları gibi F# yapıları, bildirimlerinden hemen önce bir /// açıklamayla belgelenir. Gerekirse, sınıfların örtük oluşturucuları, bağımsız değişken listesinden önce bir /// açıklama verilerek belgelenir. Örneğin:

/// This is the type
type SomeType
      /// This is the implicit constructor
      (a: int, b: int) =

    /// This is the member
    member _.Sum() = a + b

Sınırlamalar

C# ve diğer .NET dillerindeki XML belgelerinin bazı özellikleri F# dilinde desteklenmez.

  • F# dilinde çapraz başvurular, karşılık gelen simgenin tam XML imzasını kullanmalıdır, örneğin cref="T:System.Console". gibi cref="Console" basit C#stili çapraz başvurular tam XML imzaları için ayrıntılı değildir ve bu öğeler F# derleyicisi tarafından denetlenmemektedir. Bazı belge araçları, sonraki işlemlerde bu çapraz başvuruların kullanılmasına izin verebilir, ancak tam imzalar kullanılmalıdır.

  • etiketleri <include><inheritdoc> F# derleyicisi tarafından desteklenmez. Kullanıldıklarında hata verilmez, ancak oluşturulan belgeler başka bir şekilde etkilenmeden yalnızca oluşturulan belge dosyasına kopyalanır.

  • Çapraz başvurular, kullanıldığında bile -warnon:3390 F# derleyicisi tarafından denetlenmiyor.

  • Etiketlerde <typeparam> kullanılan ve <typeparamref> kullanıldığında bile --warnon:3390 F# derleyicisi tarafından denetlenmeyen adlar.

  • Belgeler eksikse, kullanıldığında bile --warnon:3390 hiçbir uyarı verilmez.

Öneriler

Birçok nedenden dolayı kodun belgelenmesi önerilir. Aşağıda, F# kodunuzda XML belge etiketlerini kullanırken bilmeniz gereken bazı en iyi yöntemler, genel kullanım örneği senaryoları ve bilmeniz gerekenler yer almaktadır.

  • XML belgelerinizin geçerli XML olduğundan emin olmak için kodunuzda seçeneğini --warnon:3390 etkinleştirin.

  • Uzun XML belge açıklamalarını uygulamanızdan ayırmak için imza dosyaları eklemeyi göz önünde bulundurun.

  • Tutarlılık açısından, herkes tarafından görülebilen tüm türler ve üyeleri belgelenmelidir. Eğer yapmak zorundaysanız, her şeyi yapın.

  • En azından modüllerin, türlerin ve üyelerinin düz /// bir açıklaması veya <summary> etiketi olmalıdır. Bu, F# düzenleme araçlarının otomatik tamamlama araç ipucu penceresinde gösterilir.

  • Belge metni, tam duraklarla biten tümceler kullanılarak yazılmalıdır.

Ayrıca bkz.