No synopsis rendered for modules for Stdlib modules

[Julow]

module M : sig
  (** Doc for [M]. *)
end

In this example, the page for the top-level module doesn't contain the synopsis for the module M near its definition.

Ocamldoc does this and the documentation for the Stdlib may rely on this.

cc @dbuenzli

[dbuenzli]

I'm afraid but stdlib modules still lack synopses is it maybe due to #649 ? I'm not familiar with the namespacing business done on stdlib.

In general it would be nice to actually check issues are resolved before closing them. It seems I keep on reopening issues.

It's not hard:

opam pin add odoc .
opam pin add b0 --dev
opam pin add odig --dev
odig cache clear
odig doc -u 

[dbuenzli]

I'm afraid but stdlib modules still lack synopses is it maybe due to #649 ?

I tested with master now that it's merged. Still no synopses in the Stdlib module with odig :-(

Could this maybe due to the way odig drives odoc ? I'll try to investigate a bit.

[dbuenzli]

So I think something is wrong in the way the stdlib does namespacing, since AFAIK that trick has never been properly documented, I'm not sure exactly what is wrong.

But in any case the dependencies of the Stdlib module seem off because:

> odoc compile-deps $(opam var lib)/ocaml/stdlib.cmti
CamlinternalFormatBasics b6c6694955e10001aed267571104a961
Stdlib 4b04b4eda19aa722df365141895fb347

Now I contrasted that with Base since its submodules have the synopses (when there is one). It seems base has no base.cmti so odig falls back on looking up base.cmt. This leads to:

> odoc compile-deps $(opam var lib)/base/base.cmt
…
Base__List 5d64f423db3f4984be8e1eaf1922b201
Base__Lazy 0cbde1c360bc2c98496746406b8c2cbd
…

So the references to the namespaced modules are there in Base.

I suspect odoc is correct now but it would be nice to be able to sort out what needs to be done so that the stdlib gets its synopses. I changed the scope of the issue and we can close it whenever an appropriate issue has been opened where the work needs to be done.

Finally I just checked stdlib.cmt it doesn't seem it would help in this case:

> odoc compile-deps $(opam var lib)/ocaml/stdlib.cmt 
Stdlib 4b04b4eda19aa722df365141895fb347
CamlinternalFormatBasics b6c6694955e10001aed267571104a961
CamlinternalAtomic e23fa896d12fbb1fece052ca4f655e49

[jonludlam]

The difference is because stdlib.cmt should be comparied with base__.cmt - base.ml is compiled after all the other modules, whereas base__.ml is the one (like stdlib.ml) that's compiled before. You can see this by the compile-deps of the modules that make up the libraries, which for stdlib depend on Stdlib, but for base depend on Base__ - e.g:

$ odoc compile-deps stdlib__int.cmti
CamlinternalFormatBasics 3a3ca1838627f7762f49679ce0278ad1
Stdlib c21c5d26416461b543321872a551ea0d
Stdlib__int 3fa10753598f76054469996ed2b8844e

whereas for base:

$ odoc compile-deps base__Poly0.cmt
Stdlib c21c5d26416461b543321872a551ea0d
CamlinternalFormatBasics 3a3ca1838627f7762f49679ce0278ad1
Caml d17e5f3e96d560c464682d8afebe734e
Base__Poly0 a35ef60a8823ef9d5d02dc0a7454bb6a
Base__ b121c99538352ee9e737b1b909ea4795

So it's quite possibly an artifact of that.

[dbuenzli]

@jonludlam so what is to be blamed :-) ?

My understanding is that its the stdlib's implementation of namespacing.

For reference this was done in ocaml/ocaml#1010 it seems it was recently updated in ocaml/ocaml#10169 (that didn't make it in a release yet).

[jonludlam]

Odoc is to be blamed :-)
The strategy stdlib is using is the same as used by dune when you haven't hand-written the equivalent of 'base.ml', it's certainly something we can and should support.

[Julow]

I fail to reproduce this. This way of namespacing should already be supported, we have some tests working like that. There must be something else.
My progress so far: master...Julow:test-case-stdlib
I have consistent ocamlobjinfo outputs and the commands seems to be run in the same order as Odig. Any idea?

[dbuenzli]

I fail to reproduce this

You mean you do have the synopses for the stdlib ?
Is it maybe the OCaml version maybe ? I don't see them on 4.09.1 and 4.11.1

[Julow]

You mean you do have the synopses for the stdlib ?

I have the synopses for my small reproduction case. Do you have an idea of what's missing ?
It's not the OCaml version.

[dbuenzli]

I have no idea. Maybe the way odig invokes stuff is the cluprit. If you want to have a closer look at what odig does you can after a run do:

odig log -m ocaml    # build operations for the ocaml package 
odig log -m -l ocaml  # more details 
odig log -l -w FILE # operation that wrote file `FILE`
odig log -l -r FILE # operation(s) that read file `FILE`
odig log --help  # more options 

[Octachron]

A difference that I see between the test case and the standard library is that the standard library is using (after postprocessing)

(** @canonical List*)
module List = Stdlib__List 

[Julow]

@Octachron The @canonical tag is indeed the cause, thanks !

[dbuenzli]

Thanks @Julow for the fix ! I have updated the odig sample output with odoc master and all these synopses are nicely showing up now.