.\"**************************************************************************
.\"*                                                                        *
.\"*                                 OCaml                                  *
.\"*                                                                        *
.\"*             Maxence Guesdon, projet Cristal, INRIA Rocquencourt        *
.\"*                                                                        *
.\"*   Copyright 2004 Institut National de Recherche en Informatique et     *
.\"*     en Automatique.                                                    *
.\"*                                                                        *
.\"*   All rights reserved.  This file is distributed under the terms of    *
.\"*   the GNU Lesser General Public License version 2.1, with the          *
.\"*   special exception on linking described in the file LICENSE.          *
.\"*                                                                        *
.\"**************************************************************************
.\"
.TH OCAMLDOC 1

.SH "نام (NAME)"
ocamldoc \- ابزار تولید مستندات OCaml


.SH "خلاصه دستور (SYNOPSIS)"
.B ocamldoc
[
.I گزینه‌ها
]
.IR نام‌فایل " ..."

.SH "توضیحات (DESCRIPTION)"

تولیدکننده مستندات OCaml یعنی
.BR ocamldoc (1)
مستندات را از کامنت‌های ویژه‌ای که در فایل‌های منبع تعبیه شده‌اند تولید می‌کند. کامنت‌های مورد استفاده
.B ocamldoc
به شکل
.I (** ... *)
هستند و از قالبی پیروی می‌کنند که در
.IR The\ OCaml\ user's\ manual
شرح داده شده است.

.B ocamldoc
می‌تواند مستندات را در قالب‌های گوناگونی تولید کند: HTML، LaTeX، TeXinfo، صفحات راهنمای یونیکس (man pages) و گراف‌های وابستگی
.BR dot (1).
افزون بر این، کاربران می‌توانند تولیدکننده‌های سفارشی خود را نیز بیفزایند.

در این صفحه راهنما، واژه
.I عنصر (element)
برای اشاره به هر یک از بخش‌های زیر در یک فایل منبع OCaml به کار می‌رود: تعریف نوع، مقدار، ماژول، استثنا، نوع ماژول، سازنده نوع، فیلد رکورد، کلاس، نوع کلاس، متد کلاس، مقدار کلاس یا عبارت وراثت کلاس.

.SH "گزینه‌ها (OPTIONS)"

گزینه‌های خط فرمان زیر قالب مستندات تولیدشده توسط
.BR ocamldoc (1)
را تعیین می‌کنند.
.SS "گزینه‌های انتخاب قالب خروجی (Options for choosing the output format)"
.TP
.B \-html
تولید مستندات در قالب پیش‌فرض HTML. صفحات HTML تولیدشده در دایرکتوری جاری، یا در دایرکتوری مشخص‌شده با گزینه
.B \-d
ذخیره می‌شوند. می‌توانید با ویرایش فایل
.I style.css
تولیدشده، یا با ارائه شیوه‌نامه (style sheet) اختصاصی خود با استفاده از گزینه
.BR \-css\-style ،
ظاهر صفحات تولیدشده را سفارشی‌سازی کنید. اگر فایل
.I style.css
از قبل موجود باشد، دوباره تولید نمی‌شود.
.TP
.B \-latex
تولید مستندات در قالب پیش‌فرض LaTeX. سند LaTeX تولیدشده در فایل
.IR ocamldoc.out
یا در فایل مشخص‌شده با گزینه
.B \-o
ذخیره می‌شود. این سند از فایل شیوه
.IR ocamldoc.sty
استفاده می‌کند. این فایل هنگام استفاده از گزینه
.B \-latex
تولید می‌شود، البته در صورتی که از قبل وجود نداشته باشد. می‌توانید این فایل را برای سفارشی‌سازی شیوه مستندات LaTeX خود تغییر دهید.
.TP
.B \-texi
تولید مستندات در قالب پیش‌فرض TeXinfo. سند TeXinfo تولیدشده در فایل
.IR ocamldoc.out
یا در فایل مشخص‌شده با گزینه
.B \-o
ذخیره می‌شود.
.TP
.B \-man
تولید مستندات به‌صورت مجموعه‌ای از صفحات راهنمای یونیکس (man pages). صفحات تولیدشده در دایرکتوری جاری، یا در دایرکتوری مشخص‌شده با گزینه
.B \-d
ذخیره می‌شوند.
.TP
.B \-dot
تولید یک گراف وابستگی برای ماژول‌های سطح بالا (toplevel)، در قالبی مناسب برای نمایش و پردازش توسط
.BR dot (1).
ابزار
.BR dot (1)
از نشانی
.IR https://graphviz.org
در دسترس است. نمایش متنی گراف در فایل
.IR ocamldoc.out
یا در فایل مشخص‌شده با گزینه
.B \-o
نوشته می‌شود. برای نمایش آن از دستور
.BI dot " ocamldoc.out"
استفاده کنید.
.TP
.BI \-g " file"
بارگذاری پویای فایل مشخص‌شده (که پسوند آن معمولاً .cmo یا .cma است)، که یک تولیدکننده مستندات سفارشی را تعریف می‌کند. اگر فایل داده‌شده یک نام ساده باشد و در دایرکتوری جاری وجود نداشته باشد،
.B ocamldoc
آن را در دایرکتوری پیش‌فرض تولیدکننده‌های سفارشی، و در دایرکتوری‌های مشخص‌شده با گزینه
.B \-i
جستجو می‌کند.
.TP
.BI \-customdir
نمایش دایرکتوری پیش‌فرض تولیدکننده‌های سفارشی.
.TP
.BI \-i " directory"
افزودن دایرکتوری داده‌شده به مسیر جستجوی تولیدکننده‌های سفارشی.
.SS "گزینه‌های عمومی (General options)"
.TP
.BI \-d " dir"
تولید فایل‌ها در دایرکتوری
.IR dir
به‌جای دایرکتوری جاری.
.TP
.BI \-dump " file"
تخلیه اطلاعات جمع‌آوری‌شده در
.IR file .
این اطلاعات را می‌توان با گزینه
.B \-load
در فراخوانی‌های بعدی
.BR ocamldoc (1)
بازخوانی کرد.
.TP
.BI \-hide " modules"
پنهان کردن نام‌های کامل ماژول‌های مشخص‌شده در مستندات تولیدی.
.I modules
فهرستی از نام‌های کامل ماژول‌ها است که با کاما (,) و بدون فاصله از هم جدا شده‌اند؛ برای نمونه:
.IR Stdlib,M2.M3 .
.TP
.B \-inv\-merge\-ml\-mli
معکوس کردن اولویت پیاده‌سازی‌ها و رابط‌ها (interfaces) هنگام ادغام. تمامی عناصر در فایل‌های پیاده‌سازی حفظ می‌شوند، و گزینه
.B \-m
مشخص می‌کند کدام بخش از کامنت‌های فایل‌های رابط با کامنت‌های فایل‌های پیاده‌سازی ادغام شوند.
.TP
.B \-keep\-code
حفظ همیشگی کد منبع برای مقادیر، متدها و متغیرهای نمونه، در صورت وجود. کد منبع همواره هنگام ارائه یک فایل .ml حفظ می‌شود، اما هنگام ارائه فایل .mli به‌طور پیش‌فرض نادیده گرفته می‌شود. این گزینه امکان حفظ همیشگی کد منبع را فراهم می‌کند.
.TP
.BI \-load " file"
بارگذاری اطلاعات از
.IR file
که توسط
.BR ocamldoc " \-dump"
تولید شده است. می‌توان چندین گزینه
.B \-load
را مشخص کرد.
.TP
.BI \-m " flags"
مشخص کردن گزینه‌های ادغام میان رابط‌ها و پیاده‌سازی‌ها.
.I flags
می‌تواند یک یا چند نویسه از موارد زیر باشد:

.B d
ادغام توضیحات (description)

.B a
ادغام @author

.B v
ادغام @version

.B l
ادغام @see

.B s
ادغام @since

.B o
ادغام @deprecated

.B p
ادغام @param

.B e
ادغام @raise

.B r
ادغام @return

.B A
ادغام همه‌چیز
.TP
.B \-no\-custom\-tags
اجازه ندادن به تگ‌های @ سفارشی.
.TP
.B \-no\-stop
حفظ عناصری که پس از کامنت ویژه
.B (**/**)
قرار گرفته‌اند.
.TP
.BI \-o " file"
ارسال مستندات تولیدشده به
.I file
به‌جای
.IR ocamldoc.out .
این گزینه تنها همراه با گزینه‌های
.BR \-latex "، " \-texi " یا " \-dot
کاربرد دارد.
.TP
.BI \-open " module"
باز کردن (open)
.I module
پیش از بررسی انواع (typing).
.TP
.BI \-pp " command"
هدایت (pipe) منابع از طریق پیش‌پردازنده
.IR command .
.TP
.BI \-ppx " command"
هدایت (pipe) درخت نحو انتزاعی (AST) از طریق پیش‌پردازنده
.IR command .
.TP
.BR \-show\-missed\-crossref
نمایش مواردی که امکان ارجاع متقابل (cross-reference) وجود داشته اما از دست رفته است.
.TP
.B \-sort
مرتب‌سازی فهرست ماژول‌های سطح بالا پیش از تولید مستندات.
.TP
.B \-stars
حذف نویسه‌های فاصله تا نخستین علامت ستاره ('*') در هر خط از کامنت‌ها.
.TP
.BI \-t " title"
استفاده از
.I title
به‌عنوان عنوان مستندات تولیدشده.
.TP
.BI \-text " file"
در نظر گرفتن \fIfile\fR به‌عنوان یک فایل .txt.
.TP
.BI \-intro " file"
استفاده از محتوای
.I file
به‌عنوان متن مقدمه
.B ocamldoc
(تنها برای HTML، LaTeX و TeXinfo). در HTML، این فایل برای ایجاد کل فایل "index.html" استفاده می‌شود.
.TP
.B \-v
حالت پرگو (verbose). نمایش اطلاعات پیشرفت کار.
.TP
.B \-version
چاپ رشته نسخه و خروج.
.TP
.B \-vnum
چاپ شماره نسخه کوتاه و خروج.
.TP
.B \-warn\-error
تلقی هشدارهای
.B ocamldoc
به‌عنوان خطا.
.TP
.B \-hide\-warnings
عدم چاپ هشدارهای
.B ocamldoc .
.TP
.BR \-help " یا " \-\-help
نمایش خلاصه کوتاهی از نحوه استفاده و خروج.
.SS "گزینه‌های بررسی نوع (Type-checking options)"
.BR ocamldoc (1)
برای دریافت اطلاعات انواع، بازرس نوع (type-checker) زبان OCaml را فرامی‌خواند. گزینه‌های زیر بر فاز بررسی نوع اثر می‌گذارند. این گزینه‌ها معنایی همسان با دستورهای
.BR ocamlc (1) " و " ocamlopt (1)
دارند.
.TP
.BI \-I " directory"
افزودن
.I directory
به فهرست دایرکتوری‌های جستجو برای فایل‌های رابط کامپایل‌شده (فایل‌های .cmi).
.TP
.B \-nolabels
نادیده گرفتن برچسب‌های غیراختیاری در انواع.
.TP
.B \-rectypes
مجاز دانستن انواع بازگشتی دلخواه. (گزینه
.B \-rectypes
در
.BR ocamlc (1)
را ببینید.)
.SS "گزینه‌های تولید صفحات HTML (Options for generating HTML pages)"
گزینه‌های زیر در پیوند با گزینه
.B \-html
اعمال می‌شوند:
.TP
.B \-all\-params
نمایش فهرست کامل پارامترها برای توابع و متدها.
.TP
.BI \-charset " s"
افزودن اطلاعات کدگذاری نویسه‌ها به‌صورت \fIs\fR
(پیش‌فرض \fBiso-8859-1\fR است).
.TP
.BI \-css\-style " filename"
استفاده از
.I filename
به‌عنوان فایل شیوه‌نامه آبشاری (CSS).
.TP
.B \-colorize\-code
رنگی‌سازی کدهای OCaml محصور در [ ] و \\{[ ]\\} با استفاده از رنگ‌ها برای برجسته‌سازی کلمات کلیدی و غیره. اگر قطعه‌کدها از نظر نحوی درست نباشند، رنگی اعمال نمی‌شود.
.TP
.B \-index\-only
تنها تولید فایل‌های نمایه (index).
.TP
.B \-short\-functors
استفاده از حالت خلاصه برای نمایش فانکتورها (functors):
.B "module M : functor (A:Module) -> functor (B:Module2) -> sig .. end"
به‌صورت زیر نمایش داده می‌شود:
.BR "module M (A:Module) (B:Module2) : sig .. end" .
.SS "گزینه‌های تولید فایل‌های LaTeX (Options for generating LaTeX files)"
گزینه‌های زیر در پیوند با گزینه
.B \-latex
اعمال می‌شوند:
.TP
.B \-latex\-value\-prefix prefix
تعیین یک پیشوند برای استفاده در برچسب‌های مقادیر در سند LaTeX تولیدشده. پیشوند پیش‌فرض رشته خالی است. همچنین می‌توانید از گزینه‌های
.BR \-latex\-type\-prefix ،
.BR \-latex\-exception\-prefix ،
.BR \-latex\-module\-prefix ،
.BR \-latex\-module\-type\-prefix ،
.BR \-latex\-class\-prefix ،
.BR \-latex\-class\-type\-prefix ،
.BR \-latex\-attribute\-prefix
و
.B \-latex\-method\-prefix
استفاده کنید.

این گزینه‌ها زمانی مفید هستند که برای نمونه، یک نوع و یک مقدار همنام داشته باشید. اگر پیشوندی تعیین نکنید، LaTeX از تعریف چندباره برچسب‌ها ایراد خواهد گرفت.
.TP
.BI \-latextitle " n,style"
مرتبط ساختن شماره شیوه
.I n
با دستور بخش‌بندی LaTeX مشخص‌شده در
.IR style ،
مانند
.BR section " یا " subsection .
(تنها در LaTeX.) این قابلیت هنگام درج سند تولیدشده درون یک سند LaTeX دیگر در یک سطح بخش‌بندی مشخص سودمند است. انتساب پیش‌فرض برابر ۱ برای section، ۲ برای subsection، ۳ برای subsubsection، ۴ برای paragraph و ۵ برای subparagraph است.
.TP
.B \-noheader
حذف سربرگ در مستندات تولیدشده.
.TP
.B \-notoc
تولید نکردن فهرست مطالب.
.TP
.B \-notrailer
حذف پابرگ در مستندات تولیدشده.
.TP
.B \-sepfiles
تولید یک فایل .tex به‌ازای هر ماژول سطح بالا، به‌جای فایل کلی
.IR ocamldoc.out .
.SS "گزینه‌های تولید فایل‌های TeXinfo (Options for generating TeXinfo files)"
گزینه‌های زیر در پیوند با گزینه
.B \-texi
اعمال می‌شوند:
.TP
.B \-esc8
اسکیپ کردن نویسه‌های دارای اعراب در فایل‌های Info.
.TP
.B \-info\-entry
مشخص کردن مدخل دایرکتوری Info.
.TP
.B \-info\-section
مشخص کردن بخش دایرکتوری Info.
.TP
.B \-noheader
حذف سربرگ در مستندات تولیدشده.
.TP
.B \-noindex
نساختن نمایه (index) برای فایل‌های Info.
.TP
.B \-notrailer
حذف پابرگ در مستندات تولیدشده.
.SS "گزینه‌های تولید گراف‌های dot (Options for generating dot graphs)"
گزینه‌های زیر در پیوند با گزینه
.B \-dot
اعمال می‌شوند:
.TP
.BI \-dot\-colors " colors"
مشخص کردن رنگ‌های مورد استفاده در کد dot تولیدشده. هنگام تولید وابستگی‌های ماژول،
.BR ocamldoc (1)
بسته به دایرکتوری‌هایی که ماژول‌ها در آن قرار دارند، رنگ‌های متفاوتی را برای آن‌ها به کار می‌برد. هنگام تولید وابستگی‌های انواع،
.BR ocamldoc (1)
بسته به ماژول‌هایی که انواع در آن‌ها تعریف شده‌اند، رنگ‌های متفاوتی را برای انواع استفاده می‌کند.
.I colors
فهرستی از نام‌های رنگ است که با کاما (,) جدا شده‌اند؛ مانند
.BR Red,Blue,Green .
رنگ‌های موجود مواردی هستند که توسط ابزار
.BR dot (1)
پشتیبانی می‌شوند.
.TP
.B \-dot\-include\-all
گنجاندن تمامی ماژول‌ها در خروجی
.BR dot (1)
و نه فقط ماژول‌های مشخص‌شده در خط فرمان یا بارگذاری‌شده با گزینه
.B \-load .
.TP
.B \-dot\-reduce
انجام کاهش متعدی (transitive reduction) روی گراف وابستگی پیش از ارسال کد dot به خروجی. این قابلیت در صورتی که وابستگی‌های متعدی فراوانی وجود داشته باشد که گراف را شلوغ می‌کنند سودمند است.
.TP
.B \-dot\-types
ارسال کد dot برای توصیف گراف وابستگی انواع به‌جای گراف وابستگی ماژول‌ها به خروجی.
.SS "گزینه‌های تولید فایل‌های man (Options for generating man files)"
گزینه‌های زیر در پیوند با گزینه
.B \-man
اعمال می‌شوند:
.TP
.B \-man\-mini
تولید صفحات راهنما تنها برای ماژول‌ها، انواع ماژول، کلاس‌ها و انواع کلاس، به‌جای تولید صفحات برای تمامی عناصر.
.TP
.BI \-man\-suffix " suffix"
تنظیم پسوند مورد استفاده برای نام‌فایل‌های man تولیدشده. پیش‌فرض o است؛ مانند
.IR List.o .
.TP
.BI \-man\-section " section"
تنظیم شماره بخش مورد استفاده برای نام‌فایل‌های man تولیدشده. پیش‌فرض ۳ است.


.SH "همچنین ببینید (SEE ALSO)"
.BR ocaml (1)،
.BR ocamlc (1)،
.BR ocamlopt (1).
.br
.IR The\ OCaml\ user's\ manual ،
فصل "The documentation generator".