.\"
.\" mdoc-update manual page.
.\" (C) 2008 Jonathan Pryor
.\" Author:
.\"   Jonathan Pryor (jpryor@novell.com)
.\"
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.TH "mdoc-update" 1
.SH "نام (NAME)"
mdoc-update \- ساخت و به‌روزرسانی مستندات XML از روی اسمبلی‌های دات‌نت Mono
.SH "خلاصه دستور (SYNOPSIS)"
\fBmdoc update\fR [\fIگزینه‌ها\fR]* \fIASSEMBLIES\fR
.SH "توضیحات (DESCRIPTION)"
دستور
\fBmdoc update\fR
مسئولیت انجام موارد زیر را بر عهده دارد:
.TP
.B *
ایجاد اسکلت‌های اولیه مستندات بر اساس
\fIASSEMBLIES\fR.
فرآیند ساخت اسکلت، پرونده‌های جدید
\fBmdoc\fR(5)
XML را برای هر نوع (Type) درون
\fIASSEMBLIES\fR
ایجاد کرده و اسکلت مستندات را برای هر یک از اعضای آن انواع فراهم می‌کند.
.TP
.B *
به‌روزرسانی اسکلت‌های مستندات بر اساس
\fIASSEMBLIES\fR.
مستندات موجود
\fBmdoc\fR(5)
می‌توانند به‌روزرسانی شوند تا تغییرات درون
\fIASSEMBLIES\fR
مانند انواع و اعضای اضافه‌شده را منعکس کنند، در حالی که مستندات موجود حفظ می‌شوند.
.Sp
در برخی شرایط محدود، تغییر نام‌ها رهگیری می‌شوند تا بار نگارش مستندات هنگام تغییر نام یک پارامتر به حداقل برسد.
.PP
دستور
\fBmdoc update\fR
به مستندات موجود در کد منبع متکی نیست، اگرچه می‌تواند کامنت‌های مستندسازی XML را از طریق گزینه
.B \-i
ایمپورت کند.
.PP
برای اطلاعات بیشتر به
\fBmdoc\fR(1)
و
\fBmdoc\fR(5)
مراجعه کنید.
.SH "گزینه‌ها (OPTIONS)"
.TP
.B \-\-delete
به
\fBmdoc update\fR
اجازه می‌دهد اعضا را از فایل‌های مستندات حذف کند. تنها اعضایی حذف می‌شوند که دیگر در
\fIASSEMBLIES\fR
وجود ندارند و در هیچ نسخه دیگری از اسمبلی‌ها نیز موجود نیستند.
.Sp
اگر یک نوع (Type) دیگر وجود نداشته باشد، فایل مستندات حذف
\fIنمی‌شود\fR،
بلکه تغییر نام می‌یابد تا پسوند
\fB.remove\fR
داشته باشد.
.Sp
تشخیص نسخه با استفاده از عناصر
\fI//AssemblyVersion\fR
انجام می‌شود؛ اگر هیچ عنصر
\fI//AssemblyVersion\fR
برای یک
\fI<Type>\fR
یا
\fI<Member/>\fR
خاص وجود نداشته باشد، آن‌گاه
\fI<Type>\fR
تغییر نام یافته و/یا
\fI<Member/>\fR
حذف خواهد شد.
.TP
\fB\-\-exceptions\fR[=\fISOURCES\fR]
آزمایشی. این قابلیت ۱۰۰٪ قابل اعتماد نیست، اما به عنوان کمکی برای نویسندگان مستندات در نظر گرفته شده است.
.Sp
بدنه اعضا را بررسی می‌کند تا تعیین کند چه استثناهایی (Exceptions) ممکن است از آن عضو تولید شوند.
.Sp
مقدار
\fISOURCES\fR
یک لیست اختیاری از منابع زیر است که با کاما از هم جدا شده‌اند و باید برای یافتن استثناها جستجو شوند:
.Sp
.nf
        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.
.fi
.Sp
اگر
\fISOURCES\fR
ارائه نشود (حالت پیش‌فرض)، تنها استثناهای ایجادشده در درون خود عضو مستندسازی خواهند شد.
.Sp
محدودیت‌ها: جستجوی استثناها در حال حاضر با بررسی انواع استثناهایی که به صراحت بر اساس انواع شناخته‌شده در زمان کامپایل ایجاد شده‌اند پیاده‌سازی شده است. این رویکرد محدودیت‌های زیر را دارد:
.RS
.ne 8
.TP
.B *
استثناهایی را که به صورت ضمنی در IL وجود دارند (مانند NullReferenceException و IndexOutOfRangeException) پیدا نخواهد کرد.
.TP
.B *
استثناهایی را که پرتاب (throw)
\fIنشده‌اند\fR
پیدا خواهد کرد، به عنوان مثال:
.nf

    public void CreateAnException ()
    {
        Exception e = new Exception ();
    }

.fi
.TP
.B *
فراخوانی‌های delegate و اینترفیس را «دنبال» نخواهد کرد:
.nf

    public void UsesDelegates ()
    {
        Func<int, int> a = x => {throw new Exception ();};
        a (4);
    }

.fi
برای تابع
\fIUsesDelegates()\fR
هیچ استثنایی مستندسازی نخواهد شد.
.TP
.B *
استثناهایی را پیدا می‌کند که «امکان رخ دادن ندارند»، مانند ArgumentNullException برای آرگومان‌هایی که «مشخص است» غیر تهی (non-null) هستند:
.nf

    public void A ()
    {
        B ("this parameter isn't null");
    }

    public void B (string s)
    {
        if (s == null)
            throw new ArgumentNullException ("s");
    }

.fi
در مثال بالا، اگر گزینه
\fB\-\-exceptions=asm\fR
داده شود، آن‌گاه
\fIA()\fR
به صورت پرتاب‌کننده ArgumentNullException مستند خواهد شد، در حالی که این اتفاق هرگز رخ نمی‌دهد.
.ne
.RE
.TP
\fB\-f\fR=\fIFLAG\fR
تعیین یک فلگ برای تغییر رفتار برنامه. فلگ‌های معتبر شامل موارد زیر هستند:
.RS
.ne 8
.TP
.B no-assembly-versions
مستندات
\fB\-fno-assembly-versions\fR
را در زیر ببینید.
.ne
.RE
.TP
\fB\-fno-assembly-versions\fR
از تولید عناصر
\fI/Type/AssemblyInfo/AssemblyVersion\fR
و
\fI/Type/Members/Member/AssemblyInfo\fR
خودداری می‌کند.
.Sp
این گزینه برای جلوگیری از ایجاد تغییرات مکرر و بیهوده (churn) هنگام به‌روزرسانی‌ها مفید است. در حالت عادی، اگر یک نوع یا عضو تغییر نکرده باشد اما نسخه اسمبلی تغییر کرده باشد، تمام انواع و اعضا برای در بر گرفتن یک عنصر
\fI//AssemblyVersion\fR
جدید به‌روزرسانی می‌شوند که در نتیجه حجم تغییرات نیازمند بازبینی قبل از کامیت را افزایش می‌دهد (با فرض اینکه همه تغییرات واقعاً قبل از کامیت بررسی می‌شوند).
.Sp
هشدار: این گزینه با گزینه
\fB\-\-delete\fR
تداخل نامناسبی
\fIخواهد داشت\fR،
زیرا
\fB\-\-delete\fR
از عناصر
\fI//AssemblyVersion\fR
برای رهگیری تغییرات نسخه استفاده می‌کند. بنابراین، اگر عضوی در نسخه اولیه اسمبلی وجود داشته باشد و در نسخه بعدی اسمبلی حذف شده باشد، مانند
\fISystem.Text.UTF8Encoding.GetBytes(string)\fR
(که در دات‌نت ۱.۰ وجود دارد اما در دات‌نت ۲.۰ نیست)، زمانی که گزینه‌های
\fB\-\-delete \-fno-assembly-versions\fR
مشخص شده باشند، عضو در نسخه قبلی اسمبلی وجود داشته و نسخه جاری اسمبلی شامل آن نباشد، آن عضو حذف خواهد شد.
.Sp
در نتیجه، این گزینه
\fIفقط\fR
باید زمانی مشخص شود که انواع و اعضا
\fIهرگز\fR
از یک اسمبلی حذف نخواهند شد.
.TP
\fB\-i\fR, \fB\-\-import\fR=\fIFILE\fR
ایمپورت مستندات موجود در
\fIFILE\fR.
.Sp
پرونده
\fIFILE\fR
می‌تواند حاوی XML تولیدی
\fIcsc /doc\fR
یا XML استاندارد
\fIECMA-335\fR
باشد.
.TP
\fB\-L\fR, \fB\-\-lib\fR=\fIDIRECTORY\fR
افزودن
\fIDIRECTORY\fR
به مسیر جستجوی اسمبلی‌ها، به طوری که وابستگی‌های
\fIASSEMBLIES\fR
بدون مستندسازی خود آن اسمبلی‌ها پیدا شوند.
.TP
\fB\-o\fR, \fB\-\-out\fR=\fIDIRECTORY\fR
قرار دادن اسکلت‌های تولیدشده در
\fIDIRECTORY\fR.
.Sp
هنگام به‌روزرسانی مستندات،
\fIDIRECTORY\fR
همچنین به عنوان دایرکتوری منبع عمل می‌کند.
.TP
\fB\-r\fR=\fIASSEMBLY\fR
فایل
\fIASSEMBLY\fR
یک وابستگی برای یکی از
\fIASSEMBLIES\fR
است که
\fIنباید\fR
مستندسازی شود اما برای پردازش یکی از
\fIASSEMBLIES\fR
مورد نیاز است. دایرکتوری حاوی
\fIASSEMBLY\fR
را به مسیر جستجوی اسمبلی اضافه می‌کند.
.Sp
این گزینه معادل مشخص کردن
\fB\-L\fR `\fIdirname\fR ASSEMBLY`
است.
.TP
\fB\-\-since\fR=\fIVERSION\fR
هنگام
\fIبه‌روزرسانی\fR
مستندات برای یک اسمبلی، اگر به نوع یا عضوی برخورد شود که در نسخه قبلی اسمبلی وجود نداشته است، یک عنصر
\fB<since version="\fR\fIVERSION\fR\fB"/>\fR
درج خواهد شد.
.TP
\fB\-\-type\fR=\fITYPE\fR
تنها به‌روزرسانی مستندات برای نوع
\fITYPE\fR.
.TP
.B \-h, \-?, \-\-help
نمایش پیام راهنما و خروج.
.SH "همچنین ببینید (SEE ALSO)"
.BR mdoc (1),
.BR mdoc (5),
.BR mdoc\-assemble (1),
.BR mdoc\-export\-html (1),
.BR mdoc\-validate (1)
.SH "لیست‌های پستی (MAILING LISTS)"
.TP
برای جزئیات بیشتر به http://lists.ximian.com/mailman/listinfo/mono-docs-list مراجعه کنید.
.SH "وب‌گاه (WEB SITE)"
برای جزئیات بیشتر به http://www.mono-project.com مراجعه کنید