mdoc-update(1) General Commands Manual mdoc-update(1) نام (NAME) mdoc-update - ساخت و به‌روزرسانی مستندات XML از روی اسمبلی‌های دات‌نت Mono خلاصه دستور (SYNOPSIS) mdoc update [گزینه‌ها]* ASSEMBLIES توضیحات (DESCRIPTION) دستور mdoc update مسئولیت انجام موارد زیر را بر عهده دارد: * ایجاد اسکلت‌های اولیه مستندات بر اساس ASSEMBLIES. فرآیند ساخت اسکلت، پرونده‌های جدید mdoc(5) XML را برای هر نوع (Type) درون ASSEMBLIES ایجاد کرده و اسکلت مستندات را برای هر یک از اعضای آن انواع فراهم می‌کند. * به‌روزرسانی اسکلت‌های مستندات بر اساس ASSEMBLIES. مستندات موجود mdoc(5) می‌توانند به‌روزرسانی شوند تا تغییرات درون ASSEMBLIES مانند انواع و اعضای اضافه‌شده را منعکس کنند، در حالی که مستندات موجود حفظ می‌شوند. در برخی شرایط محدود، تغییر نام‌ها رهگیری می‌شوند تا بار نگارش مستندات هنگام تغییر نام یک پارامتر به حداقل برسد. دستور mdoc update به مستندات موجود در کد منبع متکی نیست، اگرچه می‌تواند کامنت‌های مستندسازی XML را از طریق گزینه -i ایمپورت کند. برای اطلاعات بیشتر به mdoc(1) و mdoc(5) مراجعه کنید. گزینه‌ها (OPTIONS) --delete به mdoc update اجازه می‌دهد اعضا را از فایل‌های مستندات حذف کند. تنها اعضایی حذف می‌شوند که دیگر در ASSEMBLIES وجود ندارند و در هیچ نسخه دیگری از اسمبلی‌ها نیز موجود نیستند. اگر یک نوع (Type) دیگر وجود نداشته باشد، فایل مستندات حذف نمی‌شود، بلکه تغییر نام می‌یابد تا پسوند .remove داشته باشد. تشخیص نسخه با استفاده از عناصر //AssemblyVersion انجام می‌شود؛ اگر هیچ عنصر //AssemblyVersion برای یک یا خاص وجود نداشته باشد، آن‌گاه تغییر نام یافته و/یا حذف خواهد شد. --exceptions[=SOURCES] آزمایشی. این قابلیت ۱۰۰٪ قابل اعتماد نیست، اما به عنوان کمکی برای نویسندگان مستندات در نظر گرفته شده است. بدنه اعضا را بررسی می‌کند تا تعیین کند چه استثناهایی (Exceptions) ممکن است از آن عضو تولید شوند. مقدار SOURCES یک لیست اختیاری از منابع زیر است که با کاما از هم جدا شده‌اند و باید برای یافتن استثناها جستجو شوند: added Only generate elements for members added during the current program execution. This keeps mdoc-update from re-generating elements for all members (and thus prevents re-insertion for members that had the 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 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 مستند خواهد شد، در حالی که این اتفاق هرگز رخ نمی‌دهد. -f=FLAG تعیین یک فلگ برای تغییر رفتار برنامه. فلگ‌های معتبر شامل موارد زیر هستند: no-assembly-versions مستندات -fno-assembly-versions را در زیر ببینید. -fno-assembly-versions از تولید عناصر /Type/AssemblyInfo/AssemblyVersion و /Type/Members/Member/AssemblyInfo خودداری می‌کند. این گزینه برای جلوگیری از ایجاد تغییرات مکرر و بیهوده (churn) هنگام به‌روزرسانی‌ها مفید است. در حالت عادی، اگر یک نوع یا عضو تغییر نکرده باشد اما نسخه اسمبلی تغییر کرده باشد، تمام انواع و اعضا برای در بر گرفتن یک عنصر //AssemblyVersion جدید به‌روزرسانی می‌شوند که در نتیجه حجم تغییرات نیازمند بازبینی قبل از کامیت را افزایش می‌دهد (با فرض اینکه همه تغییرات واقعاً قبل از کامیت بررسی می‌شوند). هشدار: این گزینه با گزینه --delete تداخل نامناسبی خواهد داشت، زیرا --delete از عناصر //AssemblyVersion برای رهگیری تغییرات نسخه استفاده می‌کند. بنابراین، اگر عضوی در نسخه اولیه اسمبلی وجود داشته باشد و در نسخه بعدی اسمبلی حذف شده باشد، مانند System.Text.UTF8Encoding.GetBytes(string) (که در دات‌نت ۱.۰ وجود دارد اما در دات‌نت ۲.۰ نیست)، زمانی که گزینه‌های --delete -fno- assembly-versions مشخص شده باشند، عضو در نسخه قبلی اسمبلی وجود داشته و نسخه جاری اسمبلی شامل آن نباشد، آن عضو حذف خواهد شد. در نتیجه، این گزینه فقط باید زمانی مشخص شود که انواع و اعضا هرگز از یک اسمبلی حذف نخواهند شد. -i, --import=FILE ایمپورت مستندات موجود در FILE. پرونده FILE می‌تواند حاوی XML تولیدی csc /doc یا XML استاندارد ECMA-335 باشد. -L, --lib=DIRECTORY افزودن DIRECTORY به مسیر جستجوی اسمبلی‌ها، به طوری که وابستگی‌های ASSEMBLIES بدون مستندسازی خود آن اسمبلی‌ها پیدا شوند. -o, --out=DIRECTORY قرار دادن اسکلت‌های تولیدشده در DIRECTORY. هنگام به‌روزرسانی مستندات، DIRECTORY همچنین به عنوان دایرکتوری منبع عمل می‌کند. -r=ASSEMBLY فایل ASSEMBLY یک وابستگی برای یکی از ASSEMBLIES است که نباید مستندسازی شود اما برای پردازش یکی از ASSEMBLIES مورد نیاز است. دایرکتوری حاوی ASSEMBLY را به مسیر جستجوی اسمبلی اضافه می‌کند. این گزینه معادل مشخص کردن -L `dirname ASSEMBLY` است. --since=VERSION هنگام به‌روزرسانی مستندات برای یک اسمبلی، اگر به نوع یا عضوی برخورد شود که در نسخه قبلی اسمبلی وجود نداشته است، یک عنصر درج خواهد شد. --type=TYPE تنها به‌روزرسانی مستندات برای نوع TYPE. -h, -?, --help نمایش پیام راهنما و خروج. همچنین ببینید (SEE ALSO) mdoc(1), mdoc(5), mdoc-assemble(1), mdoc-export-html(1), mdoc-validate(1) لیست‌های پستی (MAILING LISTS) برای جزئیات بیشتر به http://lists.ximian.com/mailman/listinfo/mono- docs-list مراجعه کنید. وب‌گاه (WEB SITE) برای جزئیات بیشتر به http://www.mono-project.com مراجعه کنید mdoc-update(1)