Doc strings get dropped on includes across compilation units.

[dbuenzli]

Following up on https://github.com/ocaml/odoc/issues/875 it seems that comments do get lost on current master. Below the include in B has no docs. The include in A does.

> cat a.mli
module type A = sig
  type t
  (** Pliz keep me. *)
end

include A
> cat b.mli

include A.A

Just in case, the compilation steps in which I see this are:

'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'compile-targets' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/b.odoc' '/private/tmp/bla/_b0/brzo/ocaml-doc/cmti/b.cmti' > '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/b.odoc.writes'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'compile' '--pkg' 'bla' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/b.odoc' '/private/tmp/bla/_b0/brzo/ocaml-doc/cmti/b.cmti'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'compile-targets' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/a.odoc' '/private/tmp/bla/_b0/brzo/ocaml-doc/cmti/a.cmti' > '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/a.odoc.writes'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'compile' '--pkg' 'bla' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/a.odoc' '/private/tmp/bla/_b0/brzo/ocaml-doc/cmti/a.cmti'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'compile-targets' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/page-index.odoc' '/private/tmp/bla/_b0/brzo/ocaml-doc/index.mld' > '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/page-index.odoc.writes'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'compile' '--pkg' 'bla' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/page-index.odoc' '/private/tmp/bla/_b0/brzo/ocaml-doc/index.mld' '-I' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'html-deps' '/private/tmp/bla/_b0/brzo/ocaml-doc' > '/private/tmp/bla/_b0/brzo/ocaml-doc/bla.html.deps'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'html-targets' '-I' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/html' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/a.odoc' > '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/a.html.writes'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'html' '--theme-uri' '_odoc-theme' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/html' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/a.odoc' '-I' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'html-targets' '-I' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/html' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/b.odoc' > '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/b.html.writes'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'html' '--theme-uri' '_odoc-theme' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/html' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/b.odoc' '-I' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'html-targets' '-I' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/html' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/page-index.odoc' > '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/page-index.html.writes'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'html' '--theme-uri' '_odoc-theme' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/html' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/page-index.odoc' '-I' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'html-targets' '-I' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/html' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/b.odoc' > '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/b.html.writes'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'html' '--theme-uri' '_odoc-theme' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/html' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/b.odoc' '-I' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'html-targets' '-I' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/html' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/a.odoc' > '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/a.html.writes'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'html' '--theme-uri' '_odoc-theme' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/html' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/a.odoc' '-I' '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc/bla/'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'support-files-targets' '--without-theme' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/html' > '/private/tmp/bla/_b0/brzo/ocaml-doc/odoc-support-files.writes'
'/Users/dbuenzli/.opam/4.14.0/bin/odoc' 'support-files' '--without-theme' '-o' '/private/tmp/bla/_b0/brzo/ocaml-doc/html'

[edwintorok]

There seems to be something wrong with module level docs and includes indeed. Another case where docs just disappear is Re.Posix. Compare the generated docs with the mli . Even if I ensure that there is only one module level comment (with multiple everything but the last seems to be lost), only by clicking through to the docs of the included module can I see the doc comments, but not on the outer module where it was included: e.g. as in this PR .

I think the testcase in this issue is a good minimal repro case for that though.

[gasche]

This issue was reported again on Discuss today, it looks like several libraries are affected with authors reporting that the documentation of their code on ocaml.org is missing content.

(cc @jonludlam I guess?)

[dbuenzli]

This is another issue related to includes. The ocaml website seems to use it's own .odoc file renderer. The issues reported on the ocaml website are (at least)

https://github.com/ocaml/ocaml.org/issues/203 https://github.com/ocaml/ocaml.org/issues/400

[sabine]

The missing preambles (e.g. Re.Posix) will be back as soon as we get the ocaml-docs-ci pipeline updated together with ocaml.org to use the odoc html --as-json output format.

However, the issue with docstrings getting lost across includes is probably a different problem which warrants looking into it.

[dbuenzli]

I just retested this with odoc 2.4.2 and the original issue is still present.

[Julow]

I think this is due to compilation order. This branch contains a reproduction for the bug and a demonstration of the right order: https://github.com/ocaml/odoc/compare/master...Julow:odoc:dropped-comment-include-878

Dependencies between odoc compile commands are the same as between OCaml compile commands, for example with the order reversed:

  $ ocamlc -bin-annot -I . b.mli a.mli
  File "b.mli", line 1, characters 8-11:
  1 | include A.A
              ^^^
  Error: Unbound module A
  [2]

The odoc compile-deps command shows the dependency:

  $ odoc compile-deps b.cmti
  Stdlib f4b8105ebd6e6055083019140b5caac1
  CamlinternalFormatBasics 19b059febe2d4c7c479d13b2c961fa93
  B c3b20184f7d6edd6b3a3eb8781a4b862
  A ff259811f7897a9697520b85792ce0eb

[dbuenzli]

@julow I didn't understand if you mean this is a driver issue or an odoc issue.

[Julow]

This is a driver issue. A must be compiled before B.

[dbuenzli]

Thanks. I guess this explains that (this is the brzo driver, the odig driver uses the compile-deps). Sorry for the noise.