ocamldoc
Generate documentation from OCaml source code
SYNOPSIS
ocamldoc [options]
PARAMETERS
-c
Adds dir to the include path for finding compiled interface files (.cmi).
-d
Specifies the output directory for generated documentation files.
-html
Generates documentation in HTML format.
-latex
Generates documentation in LaTeX format.
-man
Generates documentation in man page format.
-o
Specifies the output file name for single-file formats (e.g., man, LaTeX, text).
-t
Sets the main title of the generated documentation.
-intro
Uses the content of the specified file as the introductory page.
-css
Specifies a custom CSS stylesheet for HTML output.
-sort
Sorts modules and types alphabetically in the generated output.
-hide
Hides the specified module from the documentation output.
-colorize-code
Enables syntax highlighting for code examples within the documentation.
-v
Enables verbose output, showing progress and detailed information.
-version
Prints the ocamldoc version and exits.
-help
Displays a summary of available options and exits.
DESCRIPTION
ocamldoc is the standard documentation generator for the OCaml programming language. It parses OCaml source files (.ml, .mli) and their associated documentation comments ((** ... *)) to produce high-quality, browsable documentation in various formats.
It supports generating documentation in HTML, LaTeX, plain text, and man pages. It understands module structure, links between modules, and supports custom styling and formatting. It's an essential tool for OCaml projects, allowing developers to generate API documentation directly from their codebase, making it easier for others to understand and use the libraries and applications.
CAVEATS
ocamldoc relies on .cmi (compiled interface) files being present in the include path to resolve types and links, similar to how ocamlc compiles.
Customization of output templates can be complex, often requiring knowledge of OCaml or specific template languages.
Parsing of code comments requires a specific format (** ... *) for proper interpretation, including special @ tags for structured data.
DOCUMENTATION COMMENTS
ocamldoc interprets comments delimited by (** ... *) as documentation. These comments can contain special @ tags (e.g., @param, @return, @see) for structured information, and basic HTML-like formatting (e.g., , , ).
USAGE WITH BUILD SYSTEMS
ocamldoc is commonly integrated into build systems like Dune or Makefiles. This automation allows documentation generation to be a seamless part of the project build process, ensuring documentation stays up-to-date with the codebase.
HISTORY
ocamldoc has been a core part of the OCaml distribution for many years, evolving alongside the language itself. Its design emphasizes deep integration with OCaml's module system and type-checking capabilities, ensuring that generated documentation accurately reflects the codebase. From simpler beginnings, it has grown to support various output formats and extensive customization, becoming the de-facto standard for OCaml project documentation.
