Kodunuzu XML açıklamalarıyla belgeleme

F # ' da Üçlü eğik çizgi (///) kod açıklamalarından belgeler oluşturabilirsiniz. XML açıklamaları, kod dosyaları (. FS) veya imza (. fsi) dosyalarındaki bildirimlerden önce olabilir.

XML belge açıklamaları, Kullanıcı tanımlı herhangi bir tür veya üyenin tanımının üzerine eklenen özel bir açıklama türüdür. Bunlar, derleme zamanında bir XML belge dosyası oluşturmak için derleyici tarafından işlenebilecekleri için özeldir. Derleyici tarafından oluşturulan XML dosyası, .NET derlemenizin yanı sıra, türler veya üyeler hakkında hızlı bilgileri göstermek için araç ipuçları kullanabilmesi için, .NET derlemeniz ile dağıtılabilir. Ayrıca, XML dosyası fsdocs gibi araçlar aracılığıyla, API başvuru Web siteleri oluşturmak için çalıştırılabilir.

Tüm diğer yorumlar gibi XML belgesi açıklamaları derleyici tarafından yok sayılır, aşağıda açıklanan seçenekler derleme zamanında açıklamaların geçerliliğini ve tamamını denetlemek için etkin değildir.

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

• Proje GenerateDocumentationFile <PropertyGroup> .fsproj dosyanızın bölümüne, derleme ile aynı kök dosya ADıNA sahip bir XML dosyası üreten bir öğe ekleyebilirsiniz. Örnek:

  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  

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

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

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

XML etiketleri olmayan Yorumlar

Bir /// yorum ile başlamadıysanız < , tüm açıklama metni hemen izleyen kod yapısına ait Özet belgeler olarak alınır. Her yapı için yalnızca kısa bir özet yazmak istediğinizde bu yöntemi kullanın.

Yorum, belge hazırlığı sırasında XML olarak kodlanır, bu nedenle, ve gibi karakterlerin kaçış olmaması < > & gerekir. Açıkça bir Özet etiketi belirtmezseniz, param veya etiket döndüren Etiketler gibi başka Etiketler belirtmemelisiniz.

Aşağıdaki örnek, XML etiketleri olmadan alternatif yöntemi gösterir. Bu örnekte, açıklama içindeki metnin tamamı bir Özet olarak değerlendirilir.

/// 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 etiketleriyle ilgili açıklamalar

Bir yorum gövdesi ile başlıyorsa < (normalde <summary> ), XML ETIKETLERI kullanılarak XML biçimli bir açıklama gövdesi olarak kabul edilir. Bu ikincisi, kısa bir Özet, ek açıklamalar, her bir parametre ve tür parametresi ve oluşturulan özel durumlar için belgeler ve dönüş değerinin bir açıklaması için ayrı notlar belirlemenizi sağlar.

Aşağıda, bir imza dosyasındaki tipik bir XML belgesi yorumu 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ım için Etiketler açıklanmaktadır:

Kullanıcı tanımlı Etiketler

Önceki Etiketler, F # derleyicisi ve tipik F # düzenleyici araçları tarafından tanınan olanları temsil eder. Ancak, bir Kullanıcı kendi etiketlerini tanımlayaücretsizdir. Fsdocs gibi araçlar, gibi ek Etiketler için destek getirir <namespacedoc> . Özel veya şirket içi belge oluşturma araçları ayrıca standart Etiketler ve HTML 'den PDF 'ye birden çok çıktı biçimi ile kullanılabilir.

Derleme zamanı denetimi

--warnon:3390Etkinleştirildiğinde, DERLEYICI XML sözdizimini ve içindeki ve etiketlerinde başvurulan parametreleri doğrular <param> <paramref> .

F # yapılarını belgeleme

Modüller, Üyeler, birleşim durumları ve kayıt alanları gibi F # yapıları, /// bildirimlerinden hemen önce bir yorum tarafından belgelenmiştir. Gerekirse, /// bağımsız değişken listesinden önce bir yorum vererek sınıfların örtük oluşturucuları belgelenmiştir. Örnek:

/// 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 dillerinde XML belgelerinin bazı özellikleri F # dilinde desteklenmez.

• F # ' da, çapraz başvuruların karşılık gelen sembolün tam XML imzasını kullanması gerekir, örneğin cref="T:System.Console" . Gibi basit C# stili çapraz başvurular cref="Console" ayrıntılı, tam XML imzalarına değildir ve bu öğeler F # derleyicisi tarafından denetlenmez. Bazı belge araçları, sonraki işleme tarafından bu çapraz başvuruların kullanılmasına izin verebilir, ancak tam imzaların kullanılması gerekir.

• Etiketler <include> , <inheritdoc> F # derleyicisi tarafından desteklenmez. Kullanıldıklarında hata verilmez, ancak oluşturulan belgeleri etkilemeden yalnızca oluşturulan belgeler dosyasına kopyalanırlar.

• Kullanıldığında bile, çapraz başvurular F # derleyicisi tarafından denetlenmez -warnon:3390 .

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

• Kullanıldığı zaman bile belgeler eksikse hiçbir uyarı verilmez --warnon:3390 .

Öneriler

Kodu belgeleme pek çok nedenden dolayı önerilir. Aşağıda, bazı en iyi yöntemler, genel kullanım örneği senaryoları ve F # kodunuzda XML belge etiketlerini kullanırken bilmeniz gereken noktalar verilmiştir.

• --warnon:3390XML belgelerinin GEÇERLI XML olduğundan emin olmak için kodunuzda seçeneğini etkinleştirin.

• Uygulamanızdaki uzun XML belge açıklamalarını ayırmak için imza dosyaları eklemeyi düşünün.

• Tutarlılık açısından, herkese açık olarak görünen tüm türler ve üyeleri açıklanmalıdır. Bunu yapmanız gerekiyorsa, bunu yapın.

• En azından, modüller, türler ve üyeleri düz bir /// yoruma veya etikete sahip olmalıdır <summary> . Bu, F # Editing araçlarında otomatik tamamlama araç ipucu penceresinde gösterilir.

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

Ayrıca bkz.

• C# XML belge açıklamaları (C# programlama kılavuzu).
• F # dil başvurusu
• Derleyici seçenekleri