| OCAMLDOC(1) | General Commands Manual | OCAMLDOC(1) |
نام (NAME)
ocamldoc - ابزار تولید مستندات OCaml
خلاصه دستور (SYNOPSIS)
ocamldoc [ گزینه‌ها ] نام‌فایل ...
توضیحات (DESCRIPTION)
تولیدکننده مستندات OCaml یعنی ocamldoc(1) مستندات را از کامنت‌های ویژه‌ای که در فایل‌های منبع تعبیه شده‌اند تولید می‌کند. کامنت‌های مورد استفاده ocamldoc به شکل (** ... *) هستند و از قالبی پیروی می‌کنند که در The OCaml user's manual شرح داده شده است.
ocamldoc می‌تواند مستندات را در قالب‌های گوناگونی تولید کند: HTML، LaTeX، TeXinfo، صفحات راهنمای یونیکس (man pages) و گراف‌های وابستگی dot(1). افزون بر این، کاربران می‌توانند تولیدکننده‌های سفارشی خود را نیز بیفزایند.
در این صفحه راهنما، واژه عنصر (element) برای اشاره به هر یک از بخش‌های زیر در یک فایل منبع OCaml به کار می‌رود: تعریف نوع، مقدار، ماژول، استثنا، نوع ماژول، سازنده نوع، فیلد رکورد، کلاس، نوع کلاس، متد کلاس، مقدار کلاس یا عبارت وراثت کلاس.
گزینه‌ها (OPTIONS)
گزینه‌های خط فرمان زیر قالب مستندات تولیدشده توسط ocamldoc(1) را تعیین می‌کنند.
گزینه‌های انتخاب قالب خروجی (Options for choosing the output format)
- -html
- تولید مستندات در قالب پیش‌فرض HTML. صفحات HTML تولیدشده در دایرکتوری جاری، یا در دایرکتوری مشخص‌شده با گزینه -d ذخیره می‌شوند. می‌توانید با ویرایش فایل style.css تولیدشده، یا با ارائه شیوه‌نامه (style sheet) اختصاصی خود با استفاده از گزینه -css-style، ظاهر صفحات تولیدشده را سفارشی‌سازی کنید. اگر فایل style.css از قبل موجود باشد، دوباره تولید نمی‌شود.
- -latex
- تولید مستندات در قالب پیش‌فرض LaTeX. سند LaTeX تولیدشده در فایل ocamldoc.out یا در فایل مشخص‌شده با گزینه -o ذخیره می‌شود. این سند از فایل شیوه ocamldoc.sty استفاده می‌کند. این فایل هنگام استفاده از گزینه -latex تولید می‌شود، البته در صورتی که از قبل وجود نداشته باشد. می‌توانید این فایل را برای سفارشی‌سازی شیوه مستندات LaTeX خود تغییر دهید.
- -texi
- تولید مستندات در قالب پیش‌فرض TeXinfo. سند TeXinfo تولیدشده در فایل ocamldoc.out یا در فایل مشخص‌شده با گزینه -o ذخیره می‌شود.
- -man
- تولید مستندات به‌صورت مجموعه‌ای از صفحات راهنمای یونیکس (man pages). صفحات تولیدشده در دایرکتوری جاری، یا در دایرکتوری مشخص‌شده با گزینه -d ذخیره می‌شوند.
- -dot
- تولید یک گراف وابستگی برای ماژول‌های سطح بالا (toplevel)، در قالبی مناسب برای نمایش و پردازش توسط dot(1). ابزار dot(1) از نشانی https://graphviz.org در دسترس است. نمایش متنی گراف در فایل ocamldoc.out یا در فایل مشخص‌شده با گزینه -o نوشته می‌شود. برای نمایش آن از دستور dot ocamldoc.out استفاده کنید.
- -g file
- بارگذاری پویای فایل مشخص‌شده (که پسوند آن معمولاً .cmo یا .cma است)، که یک تولیدکننده مستندات سفارشی را تعریف می‌کند. اگر فایل داده‌شده یک نام ساده باشد و در دایرکتوری جاری وجود نداشته باشد، ocamldoc آن را در دایرکتوری پیش‌فرض تولیدکننده‌های سفارشی، و در دایرکتوری‌های مشخص‌شده با گزینه -i جستجو می‌کند.
- -customdir
- نمایش دایرکتوری پیش‌فرض تولیدکننده‌های سفارشی.
- -i directory
- افزودن دایرکتوری داده‌شده به مسیر جستجوی تولیدکننده‌های سفارشی.
گزینه‌های عمومی (General options)
- -d dir
- تولید فایل‌ها در دایرکتوری dir به‌جای دایرکتوری جاری.
- -dump file
- تخلیه اطلاعات جمع‌آوری‌شده در file. این اطلاعات را می‌توان با گزینه -load در فراخوانی‌های بعدی ocamldoc(1) بازخوانی کرد.
- -hide modules
- پنهان کردن نام‌های کامل ماژول‌های مشخص‌شده در مستندات تولیدی. modules فهرستی از نام‌های کامل ماژول‌ها است که با کاما (,) و بدون فاصله از هم جدا شده‌اند؛ برای نمونه: Stdlib,M2.M3.
- -inv-merge-ml-mli
- معکوس کردن اولویت پیاده‌سازی‌ها و رابط‌ها (interfaces) هنگام ادغام. تمامی عناصر در فایل‌های پیاده‌سازی حفظ می‌شوند، و گزینه -m مشخص می‌کند کدام بخش از کامنت‌های فایل‌های رابط با کامنت‌های فایل‌های پیاده‌سازی ادغام شوند.
- -keep-code
- حفظ همیشگی کد منبع برای مقادیر، متدها و متغیرهای نمونه، در صورت وجود. کد منبع همواره هنگام ارائه یک فایل .ml حفظ می‌شود، اما هنگام ارائه فایل .mli به‌طور پیش‌فرض نادیده گرفته می‌شود. این گزینه امکان حفظ همیشگی کد منبع را فراهم می‌کند.
- -load file
- بارگذاری اطلاعات از file که توسط ocamldoc -dump تولید شده است. می‌توان چندین گزینه -load را مشخص کرد.
- -m flags
- مشخص کردن
گزینه‌های
ادغام میان
رابط‌ها و
پیاده‌سازی‌ها.
flags
می‌تواند
یک یا چند
نویسه از
موارد زیر
باشد:
d ادغام توضیحات (description)
a ادغام @author
v ادغام @version
l ادغام @see
s ادغام @since
o ادغام @deprecated
p ادغام @param
e ادغام @raise
r ادغام @return
A ادغام همه‌چیز
- -no-custom-tags
- اجازه ندادن به تگ‌های @ سفارشی.
- -no-stop
- حفظ عناصری که پس از کامنت ویژه (**/**) قرار گرفته‌اند.
- -o file
- ارسال مستندات تولیدشده به file به‌جای ocamldoc.out. این گزینه تنها همراه با گزینه‌های -latex، -texi یا -dot کاربرد دارد.
- -open module
- باز کردن (open) module پیش از بررسی انواع (typing).
- -pp command
- هدایت (pipe) منابع از طریق پیش‌پردازنده command.
- -ppx command
- هدایت (pipe) درخت نحو انتزاعی (AST) از طریق پیش‌پردازنده command.
- -show-missed-crossref
- نمایش مواردی که امکان ارجاع متقابل (cross-reference) وجود داشته اما از دست رفته است.
- -sort
- مرتب‌سازی فهرست ماژول‌های سطح بالا پیش از تولید مستندات.
- -stars
- حذف نویسه‌های فاصله تا نخستین علامت ستاره ('*') در هر خط از کامنت‌ها.
- -t title
- استفاده از title به‌عنوان عنوان مستندات تولیدشده.
- -text file
- در نظر گرفتن file به‌عنوان یک فایل .txt.
- -intro file
- استفاده از محتوای file به‌عنوان متن مقدمه ocamldoc (تنها برای HTML، LaTeX و TeXinfo). در HTML، این فایل برای ایجاد کل فایل "index.html" استفاده می‌شود.
- -v
- حالت پرگو (verbose). نمایش اطلاعات پیشرفت کار.
- -version
- چاپ رشته نسخه و خروج.
- -vnum
- چاپ شماره نسخه کوتاه و خروج.
- -warn-error
- تلقی هشدارهای ocamldoc به‌عنوان خطا.
- -hide-warnings
- عدم چاپ هشدارهای ocamldoc .
- -help یا --help
- نمایش خلاصه کوتاهی از نحوه استفاده و خروج.
گزینه‌های بررسی نوع (Type-checking options)
ocamldoc(1) برای دریافت اطلاعات انواع، بازرس نوع (type-checker) زبان OCaml را فرامی‌خواند. گزینه‌های زیر بر فاز بررسی نوع اثر می‌گذارند. این گزینه‌ها معنایی همسان با دستورهای ocamlc(1) و ocamlopt(1) دارند.
- -I directory
- افزودن directory به فهرست دایرکتوری‌های جستجو برای فایل‌های رابط کامپایل‌شده (فایل‌های .cmi).
- -nolabels
- نادیده گرفتن برچسب‌های غیراختیاری در انواع.
- -rectypes
- مجاز دانستن انواع بازگشتی دلخواه. (گزینه -rectypes در ocamlc(1) را ببینید.)
گزینه‌های تولید صفحات HTML (Options for generating HTML pages)
گزینه‌های زیر در پیوند با گزینه -html اعمال می‌شوند:
- -all-params
- نمایش فهرست کامل پارامترها برای توابع و متدها.
- -charset s
- افزودن اطلاعات کدگذاری نویسه‌ها به‌صورت s (پیش‌فرض iso-8859-1 است).
- -css-style filename
- استفاده از filename به‌عنوان فایل شیوه‌نامه آبشاری (CSS).
- -colorize-code
- رنگی‌سازی کدهای OCaml محصور در [ ] و \{[ ]\} با استفاده از رنگ‌ها برای برجسته‌سازی کلمات کلیدی و غیره. اگر قطعه‌کدها از نظر نحوی درست نباشند، رنگی اعمال نمی‌شود.
- -index-only
- تنها تولید فایل‌های نمایه (index).
- -short-functors
- استفاده از حالت خلاصه برای نمایش فانکتورها (functors): module M : functor (A:Module) -> functor (B:Module2) -> sig .. end به‌صورت زیر نمایش داده می‌شود: module M (A:Module) (B:Module2) : sig .. end.
گزینه‌های تولید فایل‌های LaTeX (Options for generating LaTeX files)
گزینه‌های زیر در پیوند با گزینه -latex اعمال می‌شوند:
- -latex-value-prefix prefix
- تعیین یک
پیشوند
برای
استفاده در
برچسب‌های
مقادیر در
سند LaTeX
تولیدشده.
پیشوند
پیش‌فرض
رشته خالی
است. همچنین
می‌توانید
از
گزینه‌های
-latex-type-prefix، -latex-exception-prefix،
-latex-module-prefix،
-latex-module-type-prefix،
-latex-class-prefix، -latex-class-type-prefix،
-latex-attribute-prefix و -latex-method-prefix
استفاده
کنید.
این گزینه‌ها زمانی مفید هستند که برای نمونه، یک نوع و یک مقدار همنام داشته باشید. اگر پیشوندی تعیین نکنید، LaTeX از تعریف چندباره برچسب‌ها ایراد خواهد گرفت.
- -latextitle n,style
- مرتبط ساختن شماره شیوه n با دستور بخش‌بندی LaTeX مشخص‌شده در style، مانند section یا subsection. (تنها در LaTeX.) این قابلیت هنگام درج سند تولیدشده درون یک سند LaTeX دیگر در یک سطح بخش‌بندی مشخص سودمند است. انتساب پیش‌فرض برابر ۱ برای section، ۲ برای subsection، ۳ برای subsubsection، ۴ برای paragraph و ۵ برای subparagraph است.
- -noheader
- حذف سربرگ در مستندات تولیدشده.
- -notoc
- تولید نکردن فهرست مطالب.
- -notrailer
- حذف پابرگ در مستندات تولیدشده.
- -sepfiles
- تولید یک فایل .tex به‌ازای هر ماژول سطح بالا، به‌جای فایل کلی ocamldoc.out.
گزینه‌های تولید فایل‌های TeXinfo (Options for generating TeXinfo files)
گزینه‌های زیر در پیوند با گزینه -texi اعمال می‌شوند:
- -esc8
- اسکیپ کردن نویسه‌های دارای اعراب در فایل‌های Info.
- -info-entry
- مشخص کردن مدخل دایرکتوری Info.
- -info-section
- مشخص کردن بخش دایرکتوری Info.
- -noheader
- حذف سربرگ در مستندات تولیدشده.
- -noindex
- نساختن نمایه (index) برای فایل‌های Info.
- -notrailer
- حذف پابرگ در مستندات تولیدشده.
گزینه‌های تولید گراف‌های dot (Options for generating dot graphs)
گزینه‌های زیر در پیوند با گزینه -dot اعمال می‌شوند:
- -dot-colors colors
- مشخص کردن رنگ‌های مورد استفاده در کد dot تولیدشده. هنگام تولید وابستگی‌های ماژول، ocamldoc(1) بسته به دایرکتوری‌هایی که ماژول‌ها در آن قرار دارند، رنگ‌های متفاوتی را برای آن‌ها به کار می‌برد. هنگام تولید وابستگی‌های انواع، ocamldoc(1) بسته به ماژول‌هایی که انواع در آن‌ها تعریف شده‌اند، رنگ‌های متفاوتی را برای انواع استفاده می‌کند. colors فهرستی از نام‌های رنگ است که با کاما (,) جدا شده‌اند؛ مانند Red,Blue,Green. رنگ‌های موجود مواردی هستند که توسط ابزار dot(1) پشتیبانی می‌شوند.
- -dot-include-all
- گنجاندن تمامی ماژول‌ها در خروجی dot(1) و نه فقط ماژول‌های مشخص‌شده در خط فرمان یا بارگذاری‌شده با گزینه -load .
- -dot-reduce
- انجام کاهش متعدی (transitive reduction) روی گراف وابستگی پیش از ارسال کد dot به خروجی. این قابلیت در صورتی که وابستگی‌های متعدی فراوانی وجود داشته باشد که گراف را شلوغ می‌کنند سودمند است.
- -dot-types
- ارسال کد dot برای توصیف گراف وابستگی انواع به‌جای گراف وابستگی ماژول‌ها به خروجی.
گزینه‌های تولید فایل‌های man (Options for generating man files)
گزینه‌های زیر در پیوند با گزینه -man اعمال می‌شوند:
- -man-mini
- تولید صفحات راهنما تنها برای ماژول‌ها، انواع ماژول، کلاس‌ها و انواع کلاس، به‌جای تولید صفحات برای تمامی عناصر.
- -man-suffix suffix
- تنظیم پسوند مورد استفاده برای نام‌فایل‌های man تولیدشده. پیش‌فرض o است؛ مانند List.o.
- -man-section section
- تنظیم شماره بخش مورد استفاده برای نام‌فایل‌های man تولیدشده. پیش‌فرض ۳ است.
همچنین ببینید (SEE ALSO)
ocaml(1)، ocamlc(1)،
ocamlopt(1).
The OCaml user's manual،
فصل "The documentation generator".