نام (NAME)

monodocer - پشتیبانی از قالب مستندسازی ECMA

خلاصه دستور (SYNOPSIS)

monodocer [OPTIONS]*

گزینه‌ها (OPTIONS)

-assembly:ASSEMBLY

ASSEMBLY یک اسمبلی دات‌نت (.NET) است که چارچوب‌های مستندسازی (stubs) برای آن ایجاد می‌شود.

یک مسیر فایل یا نام یک اسمبلی ثبت‌شده در GAC را مشخص کنید.

-delete

اجازه دادن به monodocer برای حذف اعضا از فایل‌های مستندات. تنها اعضایی حذف می‌شوند که دیگر در درون اسمبلی حضور ندارند.

اگر یک نوع (type) دیگر وجود نداشته باشد، فایل مستندات حذف نمی‌شود، بلکه در عوض با پسوند .remove تغییر نام می‌یابد.

-?, -help

نمایش اطلاعات آرگومان‌های برنامه.

-ignoremembers

اعضا به‌روزرسانی نشوند.

این گزینه چارچوب‌های مستندسازی را برای نوع‌های اضافه‌شده درج می‌کند، اما مستندات هیچ‌یک از اعضای هیچ نوعی را (شامل نوع‌های جدیداً اضافه‌شده) اضافه یا حذف نخواهد کرد.

-importslashdoc:FILE

FILE یک فایل XML است که توسط پرچم /doc:FILE در کامپایلر C# تولید شده است (برای مثال mcs -doc:foo.xml foo.cs ). مستندات اعضای موجود در FILE را به قالب مستندسازی مورداستفاده توسط monodoc وارد (import) می‌کند.

-name:NAME

NAME نام پروژه‌ای است که این مستندات متعلق به آن است.

این گزینه عنصر /Overview/Title را درون فایل index.xml که در دایرکتوری مشخص‌شده توسط -path ایجاد می‌شود، تنظیم می‌کند. این مقدار توسط برخی برنامه‌ها برای اطلاعات عنوان (مانند monodocs2html ) استفاده می‌شود.

-namespace:NAMESPACE

تنها نوع‌های موجود در فضای نام (namespace) NAMESPACE به‌روزرسانی شوند.

-overrides

گنجاندن متدهای بازنویسی‌شده (overridden) در مستندات.

این کار معمولاً ضروری نیست، زیرا مرورگر مستندات مونو (Mono Documentation Browser) در هر صورت پیوندی به اعضای نوع پایه (base type) فراهم می‌کند؛ همچنین اگر نوع پایه درون همان اسمبلی باشد، monodocs2html نیز این پیوند را ایجاد خواهد کرد.

-path:OUTPUT_DIR

OUTPUT_DIR دایرکتوری است که چارچوب‌های مستندسازی جدید/به‌روزشده را در بر خواهد داشت.

-pretty

دندانه‌گذاری و قالب‌بندی مرتب فایل‌های XML.

-since:SINCE

ایجاد یک عنصر <since/> برای نوع‌ها و اعضای اضافه‌شده با مقدار SINCE .

برای مثال، در صورت استفاده از -since:"Gtk# 2.4" عنصری در عنصر Docs برای تمام نوع‌ها و اعضای نوعِ اضافه‌شده درج خواهد شد:

<since version="Gtk# 2.4" />

مرورگر مستندات مونو (Mono Documentation Browser) و monodocs2html از این عنصر برای مشخص کردن این که یک عضو در کدام نسخه اضافه شده است استفاده خواهند کرد.

-type:TYPE

تنها ایجاد/به‌روزرسانی مستندات برای نوعِ TYPE .

-updateto:PATH

هنگام به‌روزرسانی مستندات، نوشتن فایل‌های مستندات به‌روزشده در دایرکتوری PATH .

-V, -version

نمایش نسخه و اطلاعات مجوز (لایسنس). برنامه monodocer منسوخ شده و با mdoc(1) جایگزین شده است. به صفحه راهنمای mdoc-update(1) مراجعه کنید.

monodocer برنامه‌ای است که اسکلت‌های اولیه (stubs) مستندات XML را در قالب مستندات ECMA ایجاد می‌کند. این ابزار به مستندات موجود در کد منبع متکی نیست.

مزایای آن عبارتند از:

*

خوانایی کد. مستندات خوب معمولاً (الف) مفصل بوده و (ب) پر از مثال است. (برای مقایسه، مستندات Microsoft .NET Framework را که اغلب شامل یک صفحه یا بیشتر برای هر عضو است، با مستندات JavaDoc که غالباً در حد یک جمله برای هر عضو است مقایسه کنید.)

قرار دادن مستندات خوب درون کد منبع معمولاً حجم فایل منبع را به‌شدت افزایش می‌دهد، چرا که حجم مستندات می‌تواند از متدِ واقعی در حال مستندسازی بسیار طولانی‌تر باشد.

*

بومی‌سازی. قالب‌های مستندسازی درون‌کدی (مانند /doc ) هیچ پشتیبانی‌ای از چندین زبان انسانی ندارند. اگر برای اهداف مستندسازی نیاز به پشتیبانی از بیش از یک زبان انسانی دارید، monodocer بسیار سودمند است چرا که اجازه می‌دهد هر زبان دایرکتوری اختصاصی خود را داشته باشد، و monodocer می‌تواند نوع‌ها/عضوها را برای هر دایرکتوری مستندات به‌صورت جداگانه اضافه کند.

*

مدیریت. وجود تیم‌های مجزای مستندسازی و توسعه امر غیرمعمولی نیست. همچنین ممکن است تیم مستندسازی تجربه ناچیزی در زبان برنامه‌نویسی مورد استفاده داشته باشد. در چنین شرایطی، مستندسازی درون‌خطی مطلوب نیست زیرا ممکن است تیم مستندسازی هنگام به‌روزرسانی مستندات، سهواً خطایی وارد کد منبع کند. علاوه بر این، ممکن است به دلایل امنیتی نخواهید تیم مستندسازی به کد منبع دسترسی داشته باشد. monodocer امکان نگهداری مستندات را به‌صورت کاملاً جدا و متمایز از کد منبع مورد استفاده برای ساخت اسمبلی فراهم می‌کند.

برای تبدیل مستندات monodocer به قالبی که توسط Mono Documentation Browser (مرورگر راهنمای رومیزی یا رابط وب آن) قابل استفاده باشد، کامپایل مستندات به یک قالب بسته‌بندی‌شده (packed) ضروری است. این کار با ابزار mdassembler انجام می‌شود؛ برای مثال، می‌توانید از این زنجیره ابزار به این صورت استفاده کنید:

$ monodocer -assembly:MyWidgets -path:generated_docs
$ mdassembler --ecma generated_docs -out:MyWidgets

<?xml version="1.0"?>
<monodoc>
  <source provider="ecma" basefile="MyWidgets" path="classlib-gnome"/>
</monodoc>

هنگامی که همه فایل‌های خود (.zip، .tree و .sources) را آماده کردید، می‌توانید با دستور زیر آن‌ها را در سیستم نصب کنید:

$ cp MyWidgets.tree MyWidgets.zip MyWidgets.source `pkg-config monodoc --variable sourcesdir`

پیشوندهای نوع عضو:

E:

شناسه رشته‌ای به یک رویداد (event) اشاره دارد. نام رویداد پس از نام نوع می‌آید: E:System.AppDomain.AssemblyLoad

F:

شناسه رشته‌ای به یک فیلد اشاره دارد. نام فیلد پس از نام نوع می‌آید: F:System.Runtime.InteropServices.DllImportAttribute.SetLastError

M:

به یک سازنده (constructor) یا متد اشاره دارد. سازنده‌ها عبارت .ctor را به نام نوع اضافه می‌کنند، در حالی که متدها نام متد را (همراه با تعداد اختیاری پارامترهای جنریک) پیوست می‌کنند.

اگر سازنده یا متد آرگومان بپذیرد، این آرگومان‌ها درون پرانتز پس از نام سازنده/متد فهرست می‌شوند:

M:System.Object..ctor , M:System.String..ctor(System.Char[]) , M:System.String.Concat(System.Object) , M:System.Array.Sort``1(``0[]) , M:System.Collections.Generic.List`1..ctor , M:System.Collections.Generic.List`1.Add(`0) .

N:

به یک فضای نام (namespace) اشاره دارد، مانند N:System

P:

به یک ویژگی (property) اشاره دارد. اگر ویژگی یک نمایه‌ساز (indexer) باشد یا پارامتر بپذیرد، انواع پارامترها به نام ویژگی پیوست شده و درون پرانتز قرار می‌گیرند: P:System.String.Length , P:System.String.Chars(System.Int32) .

T:

شناسه رشته‌ای به یک نوع اشاره دارد که تعداد انواع جنریک به آن پیوست شده است: T:System.String , T:System.Collections.Generic.List`1

برای جالب‌تر شدن موضوع، انواع و اعضای جنریک دو نمایش دارند: نمایش «نامقید» (unbound) (که در مثال‌های بالا نشان داده شد)، که در آن تعداد پارامترهای جنریک به نام کلاس‌ها پیوست می‌شود. همچنین یک نمایش «مقید» (bound) وجود دارد که در آن انقیاد پارامترهای جنریک درون «{» و «}» فهرست می‌شود.

نامقید (Unbound): T:System.Collections.Generic.List`1 , T:System.Collections.Generic.Dictionary`2 .

مقید (Bound): T:System.Collections.Generic.List{System.Int32} T:System.Collections.Generic.Dictionary{System.String,System.Collections.Generic.List{System.Predicate{System.String}}} .

همان‌طور که مشاهده می‌کنید، حالت‌های مقید می‌توانند به صورت دلخواه پیچیده باشند (درست مانند جنریک‌ها).

علاوه بر این، اگر یک پارامتر جنریک به پارامتر جنریک یک نوع یا متد مقید شده باشد، «شاخص» (index) پارامتر جنریک آن نوع/متد به عنوان انقیاد به کار می‌رود؛ بنابراین با فرض

class FooType {
  public static void Foo<T> (System.Predicate<T> predicate) {}
}

تفاوت اصلی با قالب ECMA در این است که هر نوع (type) فایل اختصاصی خود را درون دایرکتوری‌ای هم‌نام با فضای نام (namespace) نوع دریافت می‌کند.

بیشتر اطلاعات موجود در مستندات نباید ویرایش شوند. این موارد شامل نام نوع ( /Type/@FullName )، رابط‌های پیاده‌سازی‌شده ( /Type/Interfaces )، اطلاعات اعضا ( /Type/Members/Member/@MemberName ، /Type/Members/Member/MemberSignature ، /Type/Members/Member/MemberType ، /Type/Members/Member/Parameters و غیره) است.

آنچه باید تغییر یابد، تمامی عناصری با متن To be added. هستند که در زیر عناصر //Docs قرار دارند (مانند /Type/Docs ، /Type/Members/Member/Docs ). محتویات عنصر Docs از نظر معنایی و ساختاری یکسان با قالب مستندسازی درون‌کدی C# است که از این عناصر (فهرست‌شده در ECMA-334 ویرایش ۳، پیوست E، بخش ۲) تشکیل شده است. موارد زیر در توصیف عناصر به کار رفته‌اند:

CREF

به یک ارجاع به کلاس (یا عضو) اشاره دارد، و رشته‌ای در قالب شرح‌داده‌شده در بخش STRING ID FORMAT در بالا است.

TEXT

متن غیر XML است و XML نباید درون آن تودرتو شود.

XML

تنها عناصر XML باید درون آن تودرتو شوند (که به‌طور غیرمستقیم ممکن است شامل متن باشند)، اما متن‌های غیر از فاصلهٔ خالی نباید گره فرزند مستقیم باشند.

XML_TEXT

متن آزاد و XML، به‌گونه‌ای که سایر عناصر XML می‌توانند درون آن تودرتو شوند.

عناصر زیر در مستندسازی استفاده می‌شوند:

<block subset="SUBSET" type="TYPE">XML_TEXT</block>

یک بلوک متنی ایجاد می‌کند که از نظر مفهومی شبیه به یک پاراگراف است، اما برای ایجاد بخش‌بندی درون متن استفاده می‌شود. تا حدودی، یک <block/> معادل برچسب HTML <h2/> است.

SUBSET همیشه باید دارای مقدار none باشد.

TYPE عنوان و قالب‌بندی مورد استفاده را مشخص می‌کند. انواع شناخته‌شده عبارتند از:

behaviors بخشی با عنوان Operation ایجاد می‌کند.

note بخشی با عنوان Note: ایجاد می‌کند.

overrides بخشی با عنوان Note to Inheritors ایجاد می‌کند.

usage بخشی با عنوان Usage ایجاد می‌کند.

<c>XML_TEXT</c>

متن را در قلمی شبیه به کد قرار می‌دهد (مشابه عنصر HTML <tt/>).

<code lang="LANGUAGE">TEXT</code>

چندین خط متن را در قلمی شبیه به کد نمایش می‌دهد (مشابه عنصر HTML <pre/>). LANGUAGE زبانی است که این بلوک کد برای آن در نظر گرفته شده است. برای مثال، اگر LANGUAGE برابر C# باشد، آن‌گاه TEXT در Mono Documentation Browser دارای برجسته‌سازی نحوی برای زبان C# خواهد شد.

<example>XML_TEXT</example>

مثالی را مشخص می‌کند که باید به‌صورت ویژه‌ای نمایش داده شود. برای مثال:

<example>
  <para>An introductory paragraph.</para>
  <code lang="C#">
    class Example {
      public static void Main ()
      {
        System.Console.WriteLine ("Hello, World!");
      }
    }
  </code>
</example>

<exception cref="CREF">XML_TEXT</exception>

استثنایی را مشخص می‌کند که می‌تواند توسط عضو مستندشده پرتاب شود.

<exception/> یک عنصر سطح بالا است و باید مستقیماً در زیر عنصر <Docs/> قرار گیرد.

CREF نوع استثنایی است که پرتاب می‌شود، در حالی که XML_TEXT شامل شرایطی است که باعث پرتاب شدن CREF می‌شود.

<exception cref="T:System.ArgumentNullException">
  <paramref name="foo" /> was <see langword="null" />.
</exception>

<list>XML</list>

یک فهرست یا جدول از موارد ایجاد می‌کند. <list/> از عناصر تودرتوی <item>XML</item> ، <listheader>XML</listheader> ، <term>XML_TEXT</term> و <description>XML_TEXT</description> استفاده می‌کند.

فهرست‌ها دارای این نحو هستند:

<list type="bullet"> <!-- or type="number" -->
  <item><term>Bullet 1</term></item>
  <item><term>Bullet 2</term></item>
  <item><term>Bullet 3</term></item>
</list>

جدول‌ها دارای این نحو هستند:

	<list type="table">
	  <listheader> <!-- listheader bolds this row -->
	    <term>Column 1</term>
	    <description>Column 2</description>
	    <description>Column 3</description>
	  </listheader>
	  <item>
	    <term>Item 1-A</term>
	    <description>Item 1-B</description>
	    <description>Item 1-C</description>
	  </item>
	  <item>
	    <term>Item 2-A</term>
	    <description>Item 2-B</description>
	    <description>Item 2-C</description>
	  </item>
	</list>
<para>XML_TEXT</para>
یک بند (پاراگراف) از
XML_TEXT
را درج می‌کند.
این برچسب برای استفاده درون برچسب‌های دیگر، مانند
<example/>
،
<remarks/>
،
<returns/>
،
<term/>
و
<description/>
(ببینید
<list/>
، در بالا)، و اکثر عناصر دیگر است.

برای مثال:
	<para>This is a paragraph of text.</para>

<param name="NAME">XML_TEXT</param>

<param/> یک عنصر سطح‌بالا است و باید مستقیماً زیر عنصر <Docs/> قرار گیرد.

پارامتر NAME را برای سازنده (constructor)، متد، یا ویژگی (property) فعلی شرح می‌دهد:

<param name="count">
  A <see cref="T:System.Int32" /> containing the number
  of widgets to process.
</param>

<paramref name="NAME" />

مشخص می‌کند که NAME یک پارامتر است.

این برچسب معمولاً NAME را به‌صورت متن مورب (italic) نمایش می‌دهد، بنابراین مکرراً به عنوان معادل عنصر HTML <i/> مورد استفاده (یا سوءاستفاده) قرار می‌گیرد. برای یک مثال، به مستندات <exception/> (در بالا) مراجعه کنید.

<permission cref="CREF">XML_TEXT</permission>

الزامات دسترسی امنیتی عضو فعلی را مستند می‌کند.

<permission/> یک عنصر سطح‌بالا است و باید مستقیماً زیر عنصر <Docs/> قرار گیرد.

CREF یک ارجاع نوع (type reference) به مجوز امنیتی مورد نیاز است، در حالی که XML_TEXT توضیحی درباره دلیل نیاز به این مجوز است.

<permission cref="T:System.Security.Permissions.FileIOPermission">
  Requires permission for reading and writing files. See 
  <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Read" />, 
  <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Write" />.
</permission>

<remarks>XML_TEXT</remarks>

حاوی اطلاعات تفصیلی درباره یک عضو است.

<remarks/> یک عنصر سطح‌بالا است و باید مستقیماً زیر عنصر <Docs/> قرار گیرد.

<remarks>Insert detailed information here.</remarks>

<returns>XML_TEXT</returns>

<remarks/> یک عنصر سطح‌بالا است و باید مستقیماً زیر عنصر <Docs/> قرار گیرد.

مقدار بازگشتی یک متد را شرح می‌دهد:

<returns>
  A <see cref="T:System.Boolean" /> specifying whether 
  or not the process can access 
  <see cref="P:Mono.Unix.UnixFileSystemInfo.FullName" />.
</returns>

<see cref="CREF" />

پیوندی به عضو مشخص‌شده درون متن فعلی ایجاد می‌کند:

<see cref="M:Some.Namespace.With.Type.Method" />

<seealso cref="CREF" />

<seealso/> یک عنصر سطح‌بالا است و باید مستقیماً زیر عنصر <Docs/> قرار گیرد.

امکان ایجاد یک مدخل را برای زیربخش See Also فراهم می‌سازد. از <see/> برای مشخص کردن پیوند از درون متن استفاده کنید.

<seealso cref="P:System.Exception.Message" />

<since version="VERSION" />

<since/> یک عنصر سطح‌بالا است و باید مستقیماً زیر عنصر <Docs/> قرار گیرد.

امکان مشخص کردن این که کدام نسخه، نوع یا عضو مشخص‌شده را معرفی کرده است فراهم می‌کند.

<since version="Gtk# 2.4" />

<summary>DESCRIPTION</summary>

<summary/> یک عنصر سطح‌بالا است و باید مستقیماً زیر عنصر <Docs/> قرار گیرد.

یک نمای کلی (مختصر!) درباره یک نوع یا عضو نوع ارائه می‌دهد.

این عنصر معمولاً به عنوان بخشی از اعلان کلاس نمایش داده می‌شود و باید شرحی به‌طور معقول کوتاه از نوع/عضو باشد. برای اطلاعات تفصیلی‌تر از <remarks/> استفاده کنید.

<typeparam name="NAME">DESCRPITION</typeparam>

<typeparam/> یک عنصر سطح‌بالا است و باید مستقیماً زیر عنصر <Docs/> قرار گیرد.

این برچسب برای توصیف پارامتر نوع در یک نوع عمومی (generic) یا متد عمومی استفاده می‌شود.

NAME نام پارامتر نوع است، در حالی که DESCRIPTION شامل شرحی از پارامتر است (برای چه کاری استفاده می‌شود، چه محدودیت‌هایی را باید رعایت کند و غیره).

<typeparam name="T">The type of the underlying collection</typeparam>

<typeparamref>

برای مشخص کردن این‌که یک کلمه پارامتر نوع است به کار می‌رود؛ جهت استفاده درون سایر بلوک‌های متنی (مثلاً درون <para/> ).

<para>If <typeparamref name="T" /> is a struct, then...</para>

<value>DESCRIPTION</value>

<value/> یک عنصر سطح‌بالا است و باید مستقیماً زیر عنصر <Docs/> قرار گیرد.

امکان توصیف یک ویژگی (property) را فراهم می‌کند..nf <value> A <see cref="T:System.String" /> containing a widget name. </value>

همچنین ببینید (SEE ALSO)

mdassembler(1), mdcs2ecma(1), mdnormalizer(1), mdvalidator(1), monodocs2html(1)

فهرست‌های پستی (MAILING LISTS)

برای جزئیات بیشتر به http://lists.ximian.com/mailman/listinfo/mono-docs-list مراجعه کنید.

وبگاه (WEB SITE)

برای جزئیات بیشتر به http://www.mono-project.com مراجعه کنید.