Dune build @doc with menhir generated files

Learning
, , ,
1

Hi,

After moving from menhir.20250912 to more recent versions, I have the following error message from odocwhen running dune build @doc

Error: While resolving the expansion of include at File "src/scripting/tableParser.mli", line 20, character 2
Hidden constructors in type 'Scripting.TableParser.MenhirInterpreter.element'

Here, TableParser is a menhir generated file, thanks to the dune stanza:

(menhir
 (modules parser)
 (merge_into tableParser)
 (flags --explain --external-tokens Parser --table --strict))

In the generated html file, the part related to the type Scripting.TableParser.MenhirInterpreter.element looks like this (when the error is considered as a warning)

type element = 

    | Element : 'a lr1state
      * 'a
      * MenhirLib.IncrementalEngine.position
      * MenhirLib.IncrementalEngine.position -> element

While with more recent versions of menhir, it looks like this

type element = 

    | Element : 'a lr1state
      * 'a
      * MenhirLib__IncrementalEngine.position
      * MenhirLib__IncrementalEngine.position -> element

Does anybody have a hint of why this happens, and how I could fix the issue (without turning odoc errors into warnings)?

Many thanks.

2

I’ve been digging into this problem a little bit.

I noticed that menhirLib.mli is not shipped anymore with the package (but menhirLib.ml still is), only .mli files for (some) submodules are. In particular, not the one of IncrementalEngine(although I still don’t understand why).

Anyway, even if it likely has to do with changes in the menhir API, I don’t really need to generate documentation for menhir generated files.

So, does anybody know how I can specify in dune not to generate documentation for menhir generated files, or, alternatively, for some files I can give the name of?

3

I believe this is a problem with the current dune rules rather than any issue with Menhir. We’re working on getting the rules updated, which should fix a lot of errors similar to this in other projects. The root cause is that odoc is missing a lot of contextual info that comes from the documentation of Menhir, and the standard dune rules make no effort to try to get that (yet). Right now, the contents of the MenhirInterpreter module are taken from OCaml’s expansion of the include, which doesn’t include any doc comments and generally a little more sparse on detail.

Until the new rules arrive, you can see a kind of preview of the extra detail if you try dune build @doc-new - which will report many more errors (from your dependencies), but not the errors you’ve been seeing from Menhir! The output will be in _build/default/_doc_new/html/docs/ .

I’m quite interested by your use-case. In your project “kind2”, if I understand it correctly, you’re building the docs for a private library, so it’s not the “standard” use case of documenting a library for other people to use. Are you then building it for people working on the codebase itself? For public libraries, the easiest way to see the odoc3-rendered docs is to use ‘odoc_driver’ or to look on ocaml.org - but for private libraries this doesn’t work.

4

Thanks for the explanation.

I agree it should not be considered as an issue with menhir. It just happens that some menhir changes raised the issue for us.

Indeed! It seems that reported errors all belong to files from the standard library. And the generated html files look fine.

Our project (which is acgtk, not kind2) currently provides binaries, not a library. We use dune build @doc to generate both the end-user documentation and the developer documentation from the CI (so that it detects ill-formed comments) and push them on gitlab pages (see index (acgtk.index)).

I must admit we didn’t look into alternative ways to generate and maintain the documentation, and we use the documentation stanza almost from the very beginning when we moved to dune, so we may have missed a lot of relevant features. Developpers might instead use odig to generate and browse the code documentation.

BTW, a quick look at the odig generated documentation seems to show a similar result to the one generated with @doc-new.