Module preamble/header detection.

[dbuenzli]

Related to #235

The way module preambles are detected is odd. Basically one expects to have anything that happens before the first header or structure item to go in the module preamble/header.

More precisely in the stdlib Int64 module I would expect all of the contents of the first comment to go in the preamble. Instead, it seems all of it put in an aside element (!?):

https://github.com/ocaml/ocaml/blob/4.07/stdlib/int64.mli#L16-L28
https://b0-system.github.io/odig/doc/ocaml/Stdlib/Int64/index.html

[dbuenzli]

Also I suspect this should explain the annoying lack of module synopses in the 4.08 docset here:

https://b0-system.github.io/odig/dev/ocaml/Stdlib/index.html#modules

[dbuenzli]

This is still an issue with the new odoc. Basically the module preamble here:

https://github.com/ocaml/ocaml/blob/4.09/stdlib/int64.mli#L16-L35

Ends up in div.odoc-content rather than header.odoc-preamble (using classification terminology from #589)

[dbuenzli]

I took the liberty to add this to the 2.0.0 milestone because it basically breaks all Stdlib module preambles and as a side effect their synopsis line in the Stdlib module.

[Julow]

I've made a reproduction test case for this issue: 113d006
This seems to be due to the stdlib__ wrapping of the stdlib. Generating the html for stdlib.odocl spits out a page for Int64 that has the module's documentation in the wrong place. The html for stdlib__int64.odocl has the documentation in the preamble (but the rest of the page is empty due to it being a "hidden" module).

[dbuenzli]

Sorry but this is not fixed, still no preamble on Stdlib modules.

[dbuenzli]

(and hence no synopses aswell in Stdlib)

[dbuenzli]

Here's yet another preamble problem that I suspect is different from the Stdlib modules.

The docset here was generated with master. The B00_lines module is missing the synopsis and its doc page has no odoc-preamble, everything is folded in odoc-content.

That seem to be because there's an open in the source before the module preamble.

[dbuenzli]

That seem to be because there's an open in the source before the module preamble.

That is fixed.

Sorry but this is not fixed, still no preamble on Stdlib modules.

Still an issue…

[dbuenzli]

More precisely. This is fixed:

This is still an issue with the new odoc. Basically the module preamble here:

https://github.com/ocaml/ocaml/blob/4.09/stdlib/int64.mli#L16-L35

Ends up in div.odoc-content rather than header.odoc-preamble (using classification terminology from #589)

But the modules here still don't have synopses.

[Julow]

Odoc doesn't do this, I tested with master and 1.5.2.
I opened an other issue: #632