OCAMLDOC(1)

💖 OCAMLDOC(1) — the OCaml documentation generator 💖

okay bestie, welcome to ocamldoc(1), from the General Commands Manual, and no cap this thing is the moment. it's the OCaml documentation generator and it's about to make your source files spill all their tea. ✨

🌸 NAME 🌸

ocamldoc — the OCaml documentation generator 🫶

✨ SYNOPSIS ✨

ocamldoc [ options ] filename ...

👑 DESCRIPTION 👑

so like. ocamldoc(1) is the OCaml documentation generator, and what it does is generate documentation straight out of the special comments you tucked into your source files. the comments it cares about are the ones shaped like (** ... *), and they follow the format described in the The OCaml user's manual. yes that's literally what it's called, i don't make the rules 💅

---

the range on this girl? iconic. ocamldoc can produce documentation in a whole bunch of formats:

• HTML
• LaTeX
• TeXinfo
• Unix man pages
• and dot(1) dependency graphs 🦋

and that's not even the best part — users can add their own custom generators. main character energy fr fr 🔥

---

🎀 one lil vocab check, bestie 🎀

in this manpage, when we say element, we mean any of these parts of an OCaml source file:

• a type declaration
• a value
• a module
• an exception
• a module type
• a type constructor
• a record field
• a class
• a class type
• a class method
• a class value
• or a class inheritance clause

lowkey memorize that list, because we're gonna be saying "element" a lot and it's giving very much essential. iykyk 💜

💖 OPTIONS 💖

okay bestie, this is the part where you pick your whole vibe. every one of these flags decides what kind of documentation ocamldoc(1) is gonna spit out for you. choose wisely, it's giving ✨destiny✨.

---

🎀 Options for choosing the output format 🎀

• -html — generate the docs as HTML, the default format. the pages land in the current directory (or wherever -d points). wanna make it cute? edit the generated style.css, or bring your own sheet with -css-style. heads up: style.css will not be regenerated if it's already there, so your edits are safe. 💅
• -latex — generate the docs as LaTeX, the default format. the document gets saved into ocamldoc.out, or into whatever file -o says. it uses the style file ocamldoc.sty, which gets generated when you use -latex if it doesn't already exist. tweak that file to customize the look. 🎀
• -texi — generate the docs in TeXinfo default format. the generated LaTeX document goes to ocamldoc.out, or to the file you name with -o.
• -man — generate the docs as a set of Unix man pages. they get stored in the current directory, or in the directory from -d.
• -dot — generate a dependency graph for the toplevel modules, in a format dot(1) can display and process. dot(1) lives over at https://graphviz.org/. the textual version of the graph goes to ocamldoc.out, or to the file from -o. run dot ocamldoc.out to actually see it. 🔥
• -g file — dynamically load file (usually a .cmo or .cma), which defines a custom documentation generator. if it's a simple file and it's not in the current directory, ocamldoc hunts for it in the custom generators' default directory and in the directories you gave with -i.
• -customdir — show the custom generators' default directory. just tells you where the magic lives.
• -i directory — add directory to the path where custom generators are searched for.

---

🌸 General options 🌸

• -d dir — write files into dir instead of the current directory.
• -dump file — dump all the collected info into file. you can read that info back later with the -load option in a subsequent invocation of ocamldoc(1).
• -hide modules — hide these complete module names from the generated docs. modules is a list of complete module names separated by commas (,), no blanks allowed. like this: Stdlib,M2.M3.
• -inv-merge-ml-mli — reverse the precedence of implementations and interfaces when merging. every element in implementation files is kept, and the -m option decides which parts of the interface file comments get merged with the implementation file comments. flip the script, basically. 🙈
• -keep-code — always keep the source code for values, methods and instance variables when it's available. source code is always kept when a .ml file is given, but by default it gets discarded when a .mli is given. this flag says "no, keep it always". 💖
• -load file — load info from file, which was produced by ocamldoc -dump. you can pass several -load options at once.
• -m flags — set the merge options between interfaces and implementations. flags can be one or several of these characters:
  • d — merge description
  • a — merge @author
  • v — merge @version
  • l — merge @see
  • s — merge @since
  • o — merge @deprecated
  • p — merge @param
  • e — merge @raise
  • r — merge @return
  • A — merge everything
• -no-custom-tags — do not allow custom @-tags. sorry, no homemade tags today.
• -no-stop — keep elements placed after the (**/**) special comment.
• -o file — send the generated documentation to file instead of ocamldoc.out. this only means anything alongside the -latex, -texi, or -dot options. periodt.
• -open module — opens module before typing.
• -pp command — pipe sources through preprocessor command.
• -ppx command — pipe the abstract syntax tree through preprocessor command.
• -show-missed-crossref — show missed cross-reference opportunities. the ones that got away 😭.
• -sort — sort the list of top-level modules before generating the docs.
• -stars — remove blank characters until the first asterisk ('*') in each line of comments.
• -t title — use title as the title for the generated documentation. main character energy.
• -text file — treat file as a .txt file.
• -intro file — use the content of file as ocamldoc text for the introduction (HTML, LaTeX and TeXinfo only). for HTML, the file is used to create the whole "index.html" file.
• -v — verbose mode. shows you progress info, so you're never left wondering. 👑
• -version — print the version string and exit.
• -vnum — print the short version number and exit.
• -warn-error — treat ocamldoc warnings as errors. spicy. 🔥
• -hide-warnings — do not print ocamldoc warnings.
• -help or --help — display a short usage summary and exit.

---

🧚 Type-checking options 🧚

ocamldoc(1) calls the OCaml type-checker to get type information. these options affect the type-checking phase, and they mean exactly the same thing as they do for ocamlc(1) and ocamlopt(1).

• -I directory — add directory to the list of directories searched for compiled interface files (.cmi files).
• -nolabels — ignore non-optional labels in types.
• -rectypes — allow arbitrary recursive types. (see the -rectypes option of ocamlc(1).)

---

🌈 Options for generating HTML pages 🌈

these apply when you're rolling with the -html option:

• -all-params — display the complete list of parameters for functions and methods.
• -charset s — add info about character encoding being s (default is iso-8859-1).
• -css-style filename — use filename as the Cascading Style Sheet file.
• -colorize-code — colorize the OCaml code enclosed in [ ] and \{[ ]\}, using colors to emphasize keywords and stuff. if the code fragments aren't syntactically correct, no color is added. no glow-up for broken code 💀.
• -index-only — generate only index files.
• -short-functors — use a short form to display functors: module M : functor (A:Module) -> functor (B:Module2) -> sig .. end gets displayed as module M (A:Module) (B:Module2) : sig .. end. so much cleaner, obsessed. ✨

---

🦋 Options for generating LaTeX files 🦋

these apply when you're rolling with the -latex option:

• -latex-value-prefix prefix — give a prefix to use for the labels of the values in the generated LaTeX document. the default prefix is the empty string. you can also use the options -latex-type-prefix, -latex-exception-prefix, -latex-module-prefix, -latex-module-type-prefix, -latex-class-prefix, -latex-class-type-prefix, -latex-attribute-prefix, and -latex-method-prefix.

these options are useful when you have, like, a type and a value with the same name. if you don't specify prefixes, LaTeX will complain about multiply defined labels. it WILL complain, bestie, it always does. 😭

• -latextitle n,style — associate style number n to the given LaTeX sectioning command style, e.g. sectionorsubsection. (LaTeX only.) this is useful when including the generated document in another LaTeX document, at a given sectioning level. the default association is 1 for section, 2 for subsection, 3 for subsubsection, 4 for paragraph and 5 for subparagraph.
• -noheader — suppress the header in the generated documentation.
• -notoc — do not generate a table of contents.
• -notrailer — suppress the trailer in the generated documentation.
• -sepfiles — generate one .tex file per toplevel module, instead of the global ocamldoc.out file.

---

🍓 Options for generating TeXinfo files 🍓

these apply when you're rolling with the -texi option:

• -esc8 — escape accented characters in Info files.
• -info-entry — specify the Info directory entry.
• -info-section — specify the section of the Info directory.
• -noheader — suppress the header in the generated documentation.
• -noindex — do not build an index for Info files.
• -notrailer — suppress the trailer in the generated documentation.

---

💜 Options for generating dot graphs 💜

these apply when you're rolling with the -dot option:

• -dot-colors colors — specify the colors to use in the generated dot code. when generating module dependencies, ocamldoc(1) uses different colors for modules depending on the directories they live in. when generating type dependencies, ocamldoc(1) uses different colors for types depending on the modules they're defined in. colors is a list of color names separated by commas (,), like Red,Blue,Green. the available colors are the ones dot(1) supports. aesthetic. 🎀
• -dot-include-all — include all modules in the dot(1) output, not just the ones given on the command line or loaded with the -load option.
• -dot-reduce — perform a transitive reduction of the dependency graph before outputting the dot code. this is useful when there are a lot of transitive dependencies cluttering up the graph. declutter the timeline, fr fr. 🧹
• -dot-types — output dot code describing the type dependency graph instead of the module dependency graph.

---

👑 Options for generating man files 👑

these apply when you're rolling with the -man option:

• -man-mini — generate man pages only for modules, module types, classes and class types, instead of pages for all elements.
• -man-suffix suffix — set the suffix used for generated man filenames. default is o, as in List.o.
• -man-section section — set the section number used for generated man filenames. default is 3.

---

🌟 SEE ALSO 🌟

• ocaml(1), ocamlc(1), ocamlopt(1).
• the OCaml user's manual, chapter "The documentation generator".

---

and that's a wrap on the whole thing, bestie 🫶 go forth and document your OCaml like the icon you are. this is OCAMLDOC(1), signing off — and yes, the page footer really does just say OCAMLDOC(1) and nothing else, no hidden version number or date hiding down there, so consider this your cute little stand-in for it. slay. 💅✨