Duplicate module preambles are generated by ocamldoc

[vicuna]

Original bug ID: 7478
Reporter: @dbuenzli
Assigned to: @Octachron
Status: resolved (set by @Octachron on 2017-08-09T09:44:37Z)
Resolution: fixed
Priority: normal
Severity: minor
Version: 4.04.0
Target version: 4.06.0 +dev/beta1/beta2/rc1
Fixed in version: 4.06.0 +dev/beta1/beta2/rc1
Category: ocamldoc
Tags: github
Monitored by: @gasche @dbuenzli

Bug description

I suspect this is not a doc attachement issue (at least the dupe doesn't happen with odoc on 4.03). With ocamldoc 4.0{4,3}.0, "Hey ho" shows up twice in the generated doc. Note that if you remove the 'open String' this doesn't happen.

Steps to reproduce

cat bla.mli

open String

(** Hey ho *)

ocamldoc -html bla.mli

[vicuna]

Comment author: @Octachron

This is indeed not so much an attachment issue, but a problem with the extraction of the module preamble within ocamldoc: ocamldoc considers that the first documentation comment is the module preamble and then skip this comment, if and only if this comment was an unattached documentation comment before any module elements.

As an illustration, the following signature does also generate a duplicated
comment:

(a.mli)
val x: unit
(** This comment will be used as amodule preamble and a documentation comment for x *)

[vicuna]

Comment author: @Octachron

A possible fix implemented in #1037 is to only use as module preamble documentation comments that occur before any module elements.

[vicuna]

Comment author: @Octachron

Fixed by the integration of the above PR.