Features

3 Features

3.1 Code highlighting

String are colored in grey (environment stre).
Comments are italicized. MlDoc correctly handles nested comments (environment come).
Keywords are typeset in boldface and blue (macro \kw).
Value, type, module and class definitions are typeset in slanted (macro \definition).
Preprocessing elements from Camlp4 are typeset in boldface and red (environment ppppe and macro \pppp):
- quotations,
- grammar extension keywords,
- and the ifdef keyword.

Some other L^AT_EX macros are provided by option -main to be used in comments:

\code: to typeset code,
\fun: for the function names, and
\module: for the module names.

3.2 Helping the programmer

A common error when writing documentation comments is forgetting to escape the ``_'' character. Thus MlDoc detects the incorrect uses of this character in the arguments of the following macros: \fun, \code, \module and \texttt. The following other characters are also automatically escaped (only if the \ has been forgotten): ``^'' and ``#''.

3.3 Automatic title generation

Several options modify MlDoc's behavior with respect to title generation. The default option is -auto.

-title

takes a string in argument to be used to format the title. Any #l character sequence will be replaced by the basename of the file in lower case, #c by the basename capitalized and #u by the basename in upper case, #e by the file extension and ## by a single # character.

-notitle

produce the same title as

-title '\label{#l#e}'

-intf

produce the same title as

-title '\section{Module \module{#c} signature}
\label{#l.mli}'

-impl

produce the same title as

-title '\section{Module \module{#c} implementation}
\label{#l.ml}'

-standalone

produce the same title as

-title '\section{Standalone program \module{#c}}
\label{#l.ml}'

-ext

if the file extension is .ml, equivalent to -impl, if it is .mli, equivalent to -intf, else produce the same title as

-title '\section{#l#e}
\label{#l#e}'

-auto

as with option -ext but if both a signature file and an implementation file exist, process the two files (signature first).

3.4 Miscellaneous

The -main option generates a compilable file with the default definitions for the needed macros and environments. It can be used as an example to customize the main file that will input the MlDoc generated files for each of the modules of a complex program.
Everything before the first documentation comment is ignored. This allows to hide some unuseful comments and/or code in the documentation.
To handle ocamllex and ocamlyacc files, comments enclosed between /*TeX and */ are recognized as documentation comments.
Files ending with extension .p4 are handled as implementation files. If both a .p4 and a .ml file exist, the -auto file detection only considers the .p4 one. This has been done to allow automatic preprocessing of .p4 files by camlp4.