jon.recoil.org
this repo has no description
1@children_order odoc_for_authors cheatsheet dune features extensions ocamldoc_differences interface driver json deprecated/ main_index odoc.document/ odoc.examples/ odoc.extension_api/ odoc.extension_registry/ odoc.html/ odoc.html_support_files/ odoc.index/ odoc.json_index/ odoc.latex/ odoc.loader/ odoc.manpage/ odoc.markdown/ odoc.model/ odoc.model_desc/ odoc.ocamlary/ odoc.occurrences/ odoc.odoc/ odoc.odoc_utils/ odoc.search/ odoc.search_html_frontend/ odoc.syntax_highlighter/ odoc.xref2/ odoc.xref_test/
2@short_title The odoc documentation generator
3
4{0 The [odoc] documentation generator}
5
6{audio:https://choum.net/panglesd/odoc.mp3}
7
8{b For a quick look at the [odoc] syntax, see the {{!cheatsheet}cheatsheet}!}
9
10{1:overview What is [odoc]?}
11
12[odoc] is a documentation generator for OCaml. It reads doc comments
13from your source files and your [.mld] files, then outputs HTML, LaTeX and
14man pages. The pages you are reading now are rendered using [odoc].
15
16Text inside doc comments (delimited by [(** ... *)]) is marked up in
17[odoc] syntax:
18
19{[
20val float_dsig : int -> float t
21(** [float_dsig d] rounds the normalised {e decimal} significand
22 of the float to the [d]th decimal fractional digit and formats
23 the result with ["%g"]. Ties are rounded towards positive
24 infinity. The result is NaN on infinities and only defined for
25 [0 <= d <= 16].
26
27 {b Warning.} The current implementation overflows on large [d]
28 and floats. *)
29]}
30
31These comments are picked up by [odoc] and {{!Fmt.float_dsig}turned into HTML}, LaTeX, or manpages.
32
33The syntax reference is a refinement of that explained in the
34{{:https://ocaml.org/manual/ocamldoc.html}OCaml manual}. The differences
35are described {{!page-ocamldoc_differences}here}.
36
37[odoc]'s main advantages over OCamldoc are:
38
39- an accurate {e cross-referencer} that can calculate links between types, modules,
40module types, and more. So if you've ever been baffled by exactly what the [t] was in [val f : A(M).t -> unit], [odoc] will link to it!
41- an {e expander}, which can expand complex module-type expressions while preserving their structure, including comment, includes, and
42more. If you've ever wondered what values there are in your module [M : Base.Applicative.S with type t := u], [odoc] will show you!
43
44{1 For Authors}
45
46For guidance on how to document your OCaml project, see {!page-odoc_for_authors}.
47
48{1 For Extension Authors}
49
50To create custom tags or code blocks, see {{!page-extensions}Writing Extensions}.
51This covers the extension API, support file registration, and critical
52pitfalls around JavaScript and SPA navigation.
53
54{1 For Integrators}
55
56To integrate [odoc] into your tool, webpage or any other
57setting, you'll need to understand {{!page-driver}how to drive [odoc]}.