ocaml-docs

# OCaml Documentation (odoc) Skill

## When to Use

Use this skill when fixing odoc documentation warnings, typically from `dune build @doc`.

**Prerequisites:** This skill covers odoc v3 syntax which is not yet in released versions of dune or odoc. You need:
- dune pinned to https://github.com/jonludlam/dune/tree/odoc-v3-rules-3.21
- odoc pinned to https://github.com/jonludlam/odoc/tree/staging

## Reference Syntax

Use path-based disambiguation `{!Path.To.kind-Name}` rather than `{!kind:Path.To.Name}`:

```ocaml
(* Correct *)
{!Jsont.exception-Error}
{!Proto.Incoming.t.constructor-Message}
{!module-Foo.module-type-Bar.exception-Baz}

(* Incorrect *)
{!exception:Jsont.Error}
{!constructor:Proto.Incoming.t.Message}
```

This allows disambiguation at any position in the path.

## Reference Kinds

- `module-` for modules
- `type-` for types
- `val-` for values
- `exception-` for exceptions
- `constructor-` for variant constructors
- `field-` for record fields
- `module-type-` for module types

## Cross-Package References

When odoc cannot resolve a reference to another package, add a documentation dependency in `dune-project`:

```lisp
(package
 (name mypackage)
 ...
 (documentation (depends other-package)))
```

Do NOT convert doc references `{!Foo}` to code markup `[Foo]` - this loses the hyperlink.

## Cross-Library References (Same Package)

When referencing modules from another library in the same package, use the full path through re-exported modules.

Example: If `claude.mli` has `module Proto = Proto`, reference proto modules as `{!Proto.Incoming}` not `{!Incoming}`.

## Missing Module Exports

If odoc reports "Couldn't find X" where X is the last path component:

1. Check if the module is re-exported in the parent module's `.mli`
2. Add `module X = X` to the parent's `.mli` if missing

## Ambiguous References

When odoc warns about ambiguity (e.g., both an exception and module named `Error`):

```ocaml
{!Jsont.exception-Error}  (* for the exception *)
{!Jsont