Arguments to the @raise tag in odoc

Learning
1

I cannot make odoc to resolve the “argument” of the @raise tag that I put in my mli.

For instance, a function in lib/utils.mli is documented as

val f: int -> int
(** My function.

    @raise Invalid_argument when the argument is approximately smallish.

and I run

opam exec --verbose -- dune build @doc @doc-private

and get

File "lib/utils.mli", line 96, character 4 to line 104, character 13:
Warning: Failed to resolve reference unresolvedroot(Invalid_argument}) Couldn't
find "Invalid_argument"

I tried changing in the mli Invalid_argument to Stdlib.Invalid_argument, to [Invalid_argument], to {!Invalid_argument}, but I always get the same warning. I looked at the odoc documentation, the reference resolution part, but I couldn’t get anything to work.

Does anyone know how to fix this and make odoc “understand” the @raise tag ?

Thanks.

1 Like
2

Dune needs some work before it can handle building docs with cross references to other packages. Until that work is complete, you can try using odoc_driver instead to build the docs, which is the tool used to build the docs for ocaml.org. There are some instructions on the website but the tl;dr is:

dune build @install
dune exec -- odoc_driver <mypackage>

You might need to pin the package first so that odoc_driver can figure out the package dependencies from opam.

1 Like