mdoc-update(1) General Commands Manual mdoc-update(1)

mdoc-update - ساخت و به‌روزرسانی مستندات XML از روی اسمبلی‌های دات‌نت Mono

mdoc update [گزینه‌ها]* ASSEMBLIES

دستور mdoc update مسئولیت انجام موارد زیر را بر عهده دارد:

*
ایجاد اسکلت‌های اولیه مستندات بر اساس ASSEMBLIES. فرآیند ساخت اسکلت، پرونده‌های جدید mdoc(5) XML را برای هر نوع (Type) درون ASSEMBLIES ایجاد کرده و اسکلت مستندات را برای هر یک از اعضای آن انواع فراهم می‌کند.
*
به‌روزرسانی اسکلت‌های مستندات بر اساس ASSEMBLIES. مستندات موجود mdoc(5) می‌توانند به‌روزرسانی شوند تا تغییرات درون ASSEMBLIES مانند انواع و اعضای اضافه‌شده را منعکس کنند، در حالی که مستندات موجود حفظ می‌شوند.

در برخی شرایط محدود، تغییر نام‌ها رهگیری می‌شوند تا بار نگارش مستندات هنگام تغییر نام یک پارامتر به حداقل برسد.

دستور mdoc update به مستندات موجود در کد منبع متکی نیست، اگرچه می‌تواند کامنت‌های مستندسازی XML را از طریق گزینه -i ایمپورت کند.

برای اطلاعات بیشتر به mdoc(1) و mdoc(5) مراجعه کنید.

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

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

تشخیص نسخه با استفاده از عناصر //AssemblyVersion انجام می‌شود؛ اگر هیچ عنصر //AssemblyVersion برای یک <Type> یا <Member/> خاص وجود نداشته باشد، آن‌گاه <Type> تغییر نام یافته و/یا <Member/> حذف خواهد شد.

آزمایشی. این قابلیت ۱۰۰٪ قابل اعتماد نیست، اما به عنوان کمکی برای نویسندگان مستندات در نظر گرفته شده است.

بدنه اعضا را بررسی می‌کند تا تعیین کند چه استثناهایی (Exceptions) ممکن است از آن عضو تولید شوند.

مقدار SOURCES یک لیست اختیاری از منابع زیر است که با کاما از هم جدا شده‌اند و باید برای یافتن استثناها جستجو شوند:

added   Only generate <exception/> elements for members
          added during the current program execution.
          This keeps mdoc-update from re-generating
          <exception/> elements for all members (and thus
          prevents re-insertion for members that had the
          <exception/> elements removed).
all     Find exceptions created in the member itself,
          references to members in the same assembly,
          and references to members in dependent
          assemblies.
asm     Find exceptions created in the member itself and
          references to members within the same assembly
          as the member.
depasm  Find exceptions created in the member itself and
          references to members within dependent
          assemblies.

اگر SOURCES ارائه نشود (حالت پیش‌فرض)، تنها استثناهای ایجادشده در درون خود عضو مستندسازی خواهند شد.

محدودیت‌ها: جستجوی استثناها در حال حاضر با بررسی انواع استثناهایی که به صراحت بر اساس انواع شناخته‌شده در زمان کامپایل ایجاد شده‌اند پیاده‌سازی شده است. این رویکرد محدودیت‌های زیر را دارد:

*
استثناهایی را که به صورت ضمنی در IL وجود دارند (مانند NullReferenceException و IndexOutOfRangeException) پیدا نخواهد کرد.
*
استثناهایی را که پرتاب (throw) نشده‌اند پیدا خواهد کرد، به عنوان مثال: 
public void CreateAnException ()
{
    Exception e = new Exception ();
}
*
فراخوانی‌های delegate و اینترفیس را «دنبال» نخواهد کرد: 
public void UsesDelegates ()
{
    Func<int, int> a = x => {throw new Exception ();};
    a (4);
}
برای تابع UsesDelegates() هیچ استثنایی مستندسازی نخواهد شد.
*
استثناهایی را پیدا می‌کند که «امکان رخ دادن ندارند»، مانند ArgumentNullException برای آرگومان‌هایی که «مشخص است» غیر تهی (non-null) هستند: 
public void A ()
{
    B ("this parameter isn't null");
}
public void B (string s)
{
    if (s == null)
        throw new ArgumentNullException ("s");
}
در مثال بالا، اگر گزینه --exceptions=asm داده شود، آن‌گاه A() به صورت پرتاب‌کننده ArgumentNullException مستند خواهد شد، در حالی که این اتفاق هرگز رخ نمی‌دهد.
تعیین یک فلگ برای تغییر رفتار برنامه. فلگ‌های معتبر شامل موارد زیر هستند:
مستندات -fno-assembly-versions را در زیر ببینید.
از تولید عناصر /Type/AssemblyInfo/AssemblyVersion و /Type/Members/Member/AssemblyInfo خودداری می‌کند.

این گزینه برای جلوگیری از ایجاد تغییرات مکرر و بیهوده (churn) هنگام به‌روزرسانی‌ها مفید است. در حالت عادی، اگر یک نوع یا عضو تغییر نکرده باشد اما نسخه اسمبلی تغییر کرده باشد، تمام انواع و اعضا برای در بر گرفتن یک عنصر //AssemblyVersion جدید به‌روزرسانی می‌شوند که در نتیجه حجم تغییرات نیازمند بازبینی قبل از کامیت را افزایش می‌دهد (با فرض اینکه همه تغییرات واقعاً قبل از کامیت بررسی می‌شوند).

هشدار: این گزینه با گزینه --delete تداخل نامناسبی خواهد داشت، زیرا --delete از عناصر //AssemblyVersion برای رهگیری تغییرات نسخه استفاده می‌کند. بنابراین، اگر عضوی در نسخه اولیه اسمبلی وجود داشته باشد و در نسخه بعدی اسمبلی حذف شده باشد، مانند System.Text.UTF8Encoding.GetBytes(string) (که در دات‌نت ۱.۰ وجود دارد اما در دات‌نت ۲.۰ نیست)، زمانی که گزینه‌های --delete -fno-assembly-versions مشخص شده باشند، عضو در نسخه قبلی اسمبلی وجود داشته و نسخه جاری اسمبلی شامل آن نباشد، آن عضو حذف خواهد شد.

در نتیجه، این گزینه فقط باید زمانی مشخص شود که انواع و اعضا هرگز از یک اسمبلی حذف نخواهند شد.

ایمپورت مستندات موجود در FILE.

پرونده FILE می‌تواند حاوی XML تولیدی csc /doc یا XML استاندارد ECMA-335 باشد.

افزودن DIRECTORY به مسیر جستجوی اسمبلی‌ها، به طوری که وابستگی‌های ASSEMBLIES بدون مستندسازی خود آن اسمبلی‌ها پیدا شوند.
قرار دادن اسکلت‌های تولیدشده در DIRECTORY.

هنگام به‌روزرسانی مستندات، DIRECTORY همچنین به عنوان دایرکتوری منبع عمل می‌کند.

فایل ASSEMBLY یک وابستگی برای یکی از ASSEMBLIES است که نباید مستندسازی شود اما برای پردازش یکی از ASSEMBLIES مورد نیاز است. دایرکتوری حاوی ASSEMBLY را به مسیر جستجوی اسمبلی اضافه می‌کند.

این گزینه معادل مشخص کردن -L `dirname ASSEMBLY` است.

هنگام به‌روزرسانی مستندات برای یک اسمبلی، اگر به نوع یا عضوی برخورد شود که در نسخه قبلی اسمبلی وجود نداشته است، یک عنصر <since version="VERSION"/> درج خواهد شد.
تنها به‌روزرسانی مستندات برای نوع TYPE.
نمایش پیام راهنما و خروج.

mdoc(1), mdoc(5), mdoc-assemble(1), mdoc-export-html(1), mdoc-validate(1)

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

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