وثائق XML (F#)
You can produce documentation من triple-slash (///) تعليمات برمجية تعليقات في F#. XML تعليقات can precede تصريحات في تعليمات برمجية ملفات (.fs) أو توقيع (.fsi) ملفات.
Generating Documentation من تعليقات
The دعم في F# for generating documentation من تعليقات هو the same كـ that في غير ذلك .NET Framework languages. كـ in غير ذلك .NET Framework languages, the -doc خيار المحول البرمجي enables you إلى produce an ملف XML that يحتوي على معلومات that you can تحويل في documentation بواسطة using a أداة such كـ Sandcastle. The documentation generated بواسطة using أدوات that are designed for استخدم مع تجميعات that are written في غير ذلك .NET Framework languages generally produce a عرض of the APIs that هو based تشغيل the compiled نموذج of F# constructs. Unless أدوات specifically دعم F#, documentation generated بواسطة these أدوات does not مطابقة the F# عرض of an API.
لمزيد من المعلومات حول كيفية إلى توليد وثائق من XML، راجع تعليقات الوثائق XML (C# البرمجة الدليل).
علامات الموصى بها
هناك طريقتان إلى كتابة تعليق وثائق XML. واحد هو لعدم استخدام علامات XML وفقط كتابة الوثائق مباشرة في تعليق الخط المائل لثلاث مرات. إذا قمت بترتيب هو، نص التعليق بأكمله هو اعتبار أنه وثائق التلخيص بنية تعليمات برمجية الذي يتبع مباشرة. استخدم هذا الأسلوب عندما تريد فقط إلى كتابة خلاصة مختصر لكل تركيبة. طريقة أخرى هو باستخدام علامات XML بتوفير وثائق مصنفة أكثر. الطريقة ثانية يسمح لك بتحديد ملاحظات منفصل لملخص مختصر، وملاحظات إضافى، ووثائق لكل معلمة و نوع معلمة، ووصفاً لقيمة الإرجاع. يصف الجدول التالي علامات XML التي تم التعرف عليها في تعليقات تعليمات برمجية # ب XML.
بناء الجملة للعلامة |
الوصف |
|---|---|
<c> text </c> |
يحدد هذا نص هو تعليمات برمجية. Th هو يمكن أن يستخدم علامة مولدات الوثائق dهوplay نص بخط التي هو مناسبة للتعليمات البرمجية. |
<summary> text </summary> |
يحدد هذا نص هو وصفاً مختصراً للعنصر البرنامج. الوصف هو الجمل عادة واحد أو الثاني. |
<remarks> text </remarks> |
يحدد هذا نص يحتوي على معلومات تكميلية حول برنامج العنصر. |
<param name="name"> description </param> |
تعين الاسم و وصف لمعلمة دالة أو أسلوب. |
<typeparam name="اسم"> وصف </typeparam> |
تعين الاسم و وصف لمعلمة نوع. |
<returns> text </returns> |
تعيين وصف هذا نص القيمة المرجعة من دالة أو الأسلوب. |
<exception cref="type"> description </exception> |
تعين نوع استثناء التي يمكن إنشاؤها والظروف تحت عليها هو طرح. |
<see cref="reference"> text </see> |
تحديد ارتباط المحول إلى عنصر آخر للبرنامج. مرجع هو الاسم كـ يظهر في ملف XML الوثائق. نص هو النص الذي يظهر في الارتباط. |
<seealso cref="المرجع"/> |
تحديد ارتباط "انظر أيضاً" وثائق أخرى نوع. مرجع هو الاسم كـ يظهر في ملف XML الوثائق. راجع أيضا الارتباطات التي عادة ما تظهر في أسفل صفحة الوثائق. |
<para> text </para> |
تحديد فقرة نص. Th هو هو المستخدم لفصل نص الموجود داخل remarksعلامة. |
المثال
الوصف
يلي هو تعليق وثائق XML نموذجي في ملف توقيع.
الرمز
/// <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: mapping:(char -> string) -> str:string -> string
المثال
الوصف
يلي مثال يظهر أسلوب بديل دون علامات XML. في ترتيب هو سبيل المثال، نص بأكمله في التعليق هو خلاصةاً بعين الاعتبار. ملاحظة إذا لم تحدد علامة تلخيص بشكل واضح، يجب عدم تعيين علامات غير ذلك، مثل paramأو returnsالعلامات.
الرمز
/// Builds a new string whose characters are the results of applying the function mapping
/// to each of the characters of the input string and concatenating the resulting
/// strings.
val collect: mapping:(char -> string) -> str:string -> string