Kodunuzu XML açıklamaları ile belgele

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.

Varsayılan olarak, XML belge açıklamaları derleyici tarafından yoksayılır. Bunu değiştirmek için --warnon:3390ayarlayın. Derleyici daha sonra XML söz dizimini ve <param> ve <paramref> etiketlerinde başvuruda bulunılan parametreleri doğrular.

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

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

  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  

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

• Visual Studio kullanarak bir uygulama geliştiriyorsanız projeye sağ tıklayın ve özelliklerseçin. Özellikler iletişim kutusunda Derleme sekmesini seçin ve XML belgeler 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

Eğer bir /// yorumu <ile başlamazsa, yorum metninin tamamı hemen izleyen kod yapısının özet belgelemesi 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'ye kodlandığından, <, >ve & gibi karakterlerin kaçışına gerek yoktur. Açıkça bir özet etiketi belirtmediğiniz takdirde, param veya returns gibi diğer etiketleri 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 < (normalde <summary>) ile başlıyorsa, 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

Önerilen Etiketler

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

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

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

--warnon:3390 etkinleştirildiğinde, derleyici XML söz dizimini ve <param> ve <paramref> etiketlerinde 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çıklamasıyla belgelenir. Gerekirse, sınıfların örtük oluşturucuları, bağımsız değişken listesinden önce bir /// açıklaması ile 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ırlama

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". cref="Console" gibi basit C#stili çapraz başvurular tam XML imzalarına ayrıntılı olarak açıklanmaz 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.

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

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

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

• --warnon:3390 kullanıldığında bile belgeler eksikse uyarı verilmez.

Öneri

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 --warnon:3390 seçeneğini 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.

• Modüller, türler ve onların üyeleri, en azından düz bir /// açıklamasına veya <summary> etiketine sahip 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.

• C# XML Belge Açıklamaları (C# Programlama Kılavuzu).
• F# Dil Referansı
• Derleyici Seçenekleri