doc-style

OCaml Comment and Documentation Style

Write ocamldoc the way a POSIX manual page is written. State what a thing is and what it does, in full sentences, and stop.

Implementations carry no comments at all unless the code cannot speak for itself.

This skill covers what to write. For odoc reference syntax, cross-package links and build warnings, see the ocaml-docs skill.

The Six Rules

1. Full sentences. Every doc comment is one or more complete sentences, each ending in a full stop. No fragments, no bullet-point shorthand, no trailing "...".
2. Manpage voice. Terse, declarative, present tense, third person. No "we", no "you", no "this function", no enthusiasm.
3. No extraneous detail. Document what a caller must know to call it. History, rationale, benchmarks, future plans and implementation trivia do not appear.
4. No connectives. No colons and no em dashes joining clauses. Split into separate sentences instead. Semicolons only inside a genuine list.
5. User-facing, not internal. Describe observable behaviour. Mention an internal only when the caller can observe it, such as time complexity, allocation behaviour, evaluation order or thread safety.
6. [f x y] is .... A function's documentation opens with the function applied to its arguments in brackets, followed by is.

Function Documentation

The doc comment follows the val declaration. Name the arguments in the bracketed application and refer to them with [x] thereafter.

val length : t -> int
(** [length t] is the number of elements in [t]. *)

val find : string -> t -> element option
(** [find name t] is the element of [t] called [name], or [None] if [t] has
    no such element. *)

val is_bot : t -> bool
(** [is_bot u] is [true] if [u] is a bot user. *)

Use is whenever the function has a meaningful result. Reserve an active verb for functions that exist for their effect.

val flush : out_channel -> unit
(** [flush oc] writes the buffered bytes of [oc] to its underlying file. *)

val set : t -> key:string -> value:string -> unit
(** [set t ~key ~value] binds [key] to [value] in [t]. Any previous binding of
    [key] is dropped. *)