نام (NAME)

mdoc - ابزار مدیریت مستندات Mono

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

mdoc command [options] [args]

نمای کلی (OVERVIEW)

mdoc یک سامانهٔ مدیریت مستندات مبتنی بر اسمبلی است.

mdoc امکان ایجاد و به‌روزرسانی قالب‌های اولیهٔ مستندات (stubs) را بر اساس محتوای یک اسمبلی فراهم می‌کند. این ابزار به مستندات موجود در کد منبع وابسته نیست.

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

*

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

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

*

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

*

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

مستندات را می‌توان با استفاده از دستور mdoc update تولید کرد:

mdoc update -o docs/en ProjectName.dll

*

برای تولید یک دایرکتوری ساده از صفحات HTML (یک فایل HTML به ازای هر نوع)، از mdoc export-html استفاده کنید:

mdoc export-html -o /srv/www/htdocs/ProjectName docs/en

*

برای استفاده از یک برنامهٔ وب ASP.NET جهت نمایش منابع، ببینید: http://anonsvn.mono-project.com/source/trunk/monodoc/engine/web.

از نسخهٔ دریافت‌شده از سورس‌کد monodoc، می‌توانید این کار را انجام دهید:

cd engine
make web

این دستور از xsp(1) برای سرو کردن برنامهٔ وب ASP.NET استفاده خواهد کرد؛ برای مشاهدهٔ مستندات، http://localhost:8080 را باز کنید.

*

برای استفاده از مرورگر مستندات monodoc(1)، ابتدا باید مستندات را سرهم‌بندی (assemble) کنید:

mdoc assemble -o ProjectName docs/en

دستور بالا فایل‌های ProjectName.tree و ProjectName.zip را ایجاد می‌کند. یک فایل اضافی ProjectName.sources نیز باید ارائه شود که مشخص می‌کند مستندات در کجای سیستم راهنما باید متصل شوند؛ این یک فایل بسیار سادهٔ XML است، مانند این:

<?xml version="1.0"?>
<monodoc>
  <source provider="ecma" basefile="ProjectName"
    path="various" />
</monodoc>

فایل پیکربندی بالا مشخص می‌کند که مستندات در قالب ECMA هستند، نام فایل پایه ProjectName است و باید در بخش "various" از درخت مستندات متصل شود. اگر می‌خواهید گره‌های مختلف تعریف‌شده در مستندات را مشاهده کنید، می‌توانید به فایل monodoc.xml که معمولاً در /usr/lib/monodoc/monodoc.xml نصب می‌شود نگاهی بیندازید.

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

cp ProjectName.tree ProjectName.zip ProjectName.source \
  `pkg-config monodoc --variable sourcesdir`

دستور بالا فایل‌ها را در دایرکتوری ثبت‌شده توسط Monodoc کپی می‌کند؛ برای انجام این کار ممکن است به دسترسی ریشه نیاز داشته باشید. دایرکتوری واقعی توسط فراخوانی pkg-config بازگردانده می‌شود.

دستورهای MDOC (MDOC COMMANDS)

mdoc assemble

mdoc export-html

mdoc export-msxdoc

mdoc help

mdoc help assemble

mdoc assemble --help

mdoc help assemble export-html update validate

mdoc update

mdoc validate

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

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

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

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

وب‌گاه (WEB SITE)

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