XML Belgeleri (F#)
Üçlü-eğik çizgi (/ /) belgelerini üretebilir kod açıklamalarını F#.xml açıklamaları, kod dosyaları (.fs) veya (.fsi) imza dosyalarını bildirimlerden önce.
Açıklamalardan belgeler oluşturma
Açıklamalardan belgeleri üretmek için destek F#'taki diğer aynıdır.net Framework diller.Diğer gibi.net Framework dil -doc derleyici seçeneği , Sandcastle gibi bir araç kullanarak belgeleri dönüştürebilirsiniz bilgileri içeren bir xml dosyası üretmek sağlar.Yazılan diğer derlemeler ile kullanılmak üzere tasarlanmış araçlar kullanılarak oluşturulan belgeler.net Framework dilleri genellikle F# yapıları derlenmiş formda tabanlı API'leri görünüm üretir.Özellikle F# Destek Araçları sürece bu araçlar tarafından oluşturulan belgeleri F# görünümü bir API ile eşleşmiyor.
xml belgeleri oluşturmak hakkında daha fazla bilgi için bkz: XML Belgeleri Yorumları (C# Programlama Kılavuzu).
Önerilen etiketler
xml belgeleri Yorum yazmak için iki yol vardır.xml etiketlerini kullanmadan belgeleri bir Üçlü eğik çizgi açıklamada doğrudan yazmanız yeterlidir biridir.Bunu yaparsanız, tüm açıklama metni hemen kod yapýsýný Özet belgelerine olarak alınır.Her yapı için kısa bir özeti yazmak istediğinizde bu yöntemi kullanın.Başka bir yöntem daha yapılandırılmış belgeler sağlamak için xml etiketlerini kullanmaktır.İkinci yöntem, kısa bir özeti, ek açıklamalar, belge her parametre ve tür parametresi ve oluşan özel durumları ve dönüş değeri bir açıklaması için ayrı Notlar belirlemenizi sağlar.F# xml kodu açıklamalarda tanınan xml etiketleri aşağıdaki tabloda açıklanmaktadır.
Etiket sözdizimi |
Description |
|---|---|
<c>metin</c> |
Belirleyen metin kodudur.Bu etiket kodunu uygun bir yazı tipi, metin görüntülemek için belge üretici tarafından kullanılabilir. |
<summary>metin</summary> |
Belirleyen metin program öğesi kısa bir açıklamasıdır.Açıklama genellikle bir veya iki cümle bağlıdır. |
<remarks>metin</remarks> |
Belirleyen metin program öğesi hakkında tamamlayıcı bilgiler içerir. |
<param name="name"> description</param> |
Ad ve açıklama için bir işlev veya yöntem parametresi belirtir. |
<typeparam name="name"> description </typeparam> |
Ad ve açıklama için bir tür parametresi belirtir. |
<returns>metin</returns> |
Belirleyen metin dönüş değeri bir işlev veya yöntem açıklanır. |
<exception cref="type">description</exception> |
Oluşturabileceğiniz özel durum ve koşullar altında atılır türünü belirtir. |
<see cref="reference">text</see> |
Başka bir program öğesi için bir satır içi bağlantı belirtir.Başvuru xml belgelerine dosyasında görünen addır.Metin bağlantı içinde gösterilen metin. |
<seealso cref="başvuru"/> |
Belgeleri başka bir türü için Ayrıca bkz: bağlantı belirtir.Başvuru xml belgelerine dosyasında görünen addır.Ayrıca bkz: bağlantılar genellikle bir belge sayfasının alt kısmında görüntülenir. |
<para>metin</para> |
Bir paragraftaki metnin belirtir.Bu metni ayırmak için kullanılan remarks etiket. |
Örnek
Description
Bir imza dosyasında tipik bir xml belgelerine açıklaması aşağıdadır.
Kod
/// <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
Örnek
Description
Aşağıdaki örnek xml etiketleri olmadan alternatif yöntemi gösterilir.Bu örnekte, tüm metin açıklamasında bir özeti olarak kabul edilir.Not Özet etiketi açıkça belirtmediğiniz takdirde, diğer etiketleri gibi belirtmemeniz gerekir, param veya returns etiketler.
Kod
/// 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