مستندات XML لاسم مساحة الاسم

Question

هل تكتب XML-DOC لاسم مساحة الاسم؟ وإذا نعم، كيف وأين؟

أعتقد أنه إذا كان ذلك ممكنا، ربما ملف فارغ تقريبا مثل هذا:

/// <summary>
/// This namespace contains stuff
/// </summary>
namespace Some.Namespace
{

}

ولكن هل هذا العمل؟ نظرا لأنك ... "أعلن"، أو على الأقل استخدام مساحة الاسم في جميع الملفات الأخرى أيضا ... وما الذي سيحدث إذا كتبت شيئا وثائق XML في مكان آخر على مساحة الاسم نفسه؟ سوف يختفي؟ أو هل سيتم دمجهم بطريقة ما؟

Answer 1

NDOC يدعم هذا من خلال الاعتراف خاص NamespaceDoc فئة تقع في كل مساحة اسم، واستخدام الوثائق من ذلك. لم أحاول ذلك، لكن Sandcastle يبدو أن يدعم نفس الخدعة.

يحرر:علي سبيل المثال:

namespace Some.Namespace
{
    /// <summary>
    /// This namespace contains stuff
    /// </summary>
    public static class NamespaceDoc
    {
    }
}

Answer 2

لا يدعم SandCastle namespacedoc مباشرة، ولكن إذا كنت تستخدم Sandcastle مساعدة ملف باني يمكنك استخدام فئة Namespacedoc المذكورة بواسطة TIM.

namespace Example
{
    /// <summary>
    ///   <para>
    ///     Summary
    ///   </para>
    /// </summary>
    /// <include file='_Namespace.xml' path='Documentation/*' />
    internal class NamespaceDoc
    {
    }
}

يمد SCHB أيضا بناء الجملة قليلا ويسمح بملائم تضمين الأمثلة مباشرة من ملفات التعليمات البرمجية. مثال _namespace.xml:

<?xml version="1.0" encoding="utf-8" ?>
<Documentation>
  <summary>
    <h1 class="heading">Example Namespace</h1>
    <para>
      This namespace is used in the following way:
    </para>

    <code source="Examples\Class.cs" lang="cs"></code>
    <code source="Examples\Class.vb" lang="vbnet"></code>

    <para>
      Hopefully this helps!
    </para>
  </summary>
</Documentation>

يتيح لك الوثائق في ملف XML كتابة ملخص قصير في التعليمات البرمجية وصف أكبر في ملف XML منفصل لملف التعليمات. وبهذه الطريقة لا تشوش الكود بكل التفاصيل وتبقى بسهولة مقروءة.

Answer 3

Sandcastle Help File Builder يدعم التعليقات على مساحات الأسماء. افتح مشروع Sandcastle الخاص بك. في Project Properties نافذة انتقل إلى Summaries وانقر على Edit Namespace Summaries زر.

Answer 4

يمكنك القيام بذلك في Doxygen باستخدام:

/// <summary>
/// description
/// </summary>
namespace name{};

أيضا، إنها ممارسات جيدة أن تعلن مساحات أعاسبك في ملف أعضاء الأسماء. وتعليقها فقط في هذا الملف.

Answer 5

إذا كنت تستخدم SandCastle و "Builder File" الخاص به "يمكنك توثيق مساحات الأسماء واسم مساحة الاسم باستخدام التعليمات البرمجية التالية في مشاريعك:

namespace Company.Product.Widgets
{
    /// <summary>
    /// These are the namespace comments for <c>Company.Product.Widgets</c>.
    /// </summary>
    [System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
    class NamespaceDoc
    {
    }
}

إذا تم تمكين مشروع مساحة الاسم، فيمكنك أيضا الحفاظ على تعليقات مجموعة الاسم المسمير باستخدام فئة NamespaceGroupdoc بطريقة مماثلة. وفيما يلي مثال على ذلك:

namespace Company.Product
{
    /// <summary>
    /// These are the group comments for namespaces in <c>Company.Product</c>.
    /// </summary>
    [System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
    class NamespaceGroupDoc
    {
    }
}

للحفاظ على فئة NamespaCedoc من الظهور في ملف التعليمات، اترك الكلمة الرئيسية العامة وتمييزها بسمة مركبة.

للرجوع اليها هنا: https://ewsoftware.github.io/shfb/html/48f5a893-acde-4e50-8c17-72b83d9c3f9d.htm.

Answer 6

لا يمكن وضع تعليقات على مساحات الأسماء.

usenamespacedocsummaries على http://ndoc.sourceforge.net/content/documenters.htm.

Answer 7

إذا كنت تستخدم كثرة الوحيدات'س mdoc. نظام الوثائق، يمكنك توثيق أعضاء مساحة الاسم عن طريق تحرير ملفات وثائق NS - *. ملفات مستندات XML.

انظر وثائق تنسيق ملف MDOC لمزيد من التفاصيل.