Documentation conventions

Where documentation lives

- A module with an [.mli] carries its documentation there, and only there. The [.ml] keeps comments that explain implementation choices. {!module-Ogit.Ui} is the reference example. - A module without an [.mli] documents itself in the [.ml]. - Every module opens with a doc comment saying what it is responsible for, and what it deliberately does not do when that boundary matters.

What is worth writing down

Prefer explaining a decision over restating a signature. [val port : int] needs no comment; the fact that a resolver failure keeps its category all the way to the HTTP boundary does.

Outstanding work

Items marked [TODO] in the sources are places where the intended behaviour is clear enough to use but has not been described. Find them with:

grep -rn 'TODO' lib bin

The package metadata in [dune-project] also still carries dune's placeholder values for [description], [documentation] and [license].