Top-level doc-comments of module types are discarded

[craigfe]

With the following set of files:

(* --- main_intf.ml --------------------------------------------- *)
module type S = sig
  (** Top-level comment *)

  val t : unit
  (** Item comment *)
end

(* --- main.ml -------------------------------------------------- *)
let t = ()

(* --- main.mli ------------------------------------------------- *)
include Main_intf.S (** @inline *)

the generated documentation for Main looks like the following:

i.e. the top-level doc-comment has been lost. As a workaround, it's possible to move top-level doc comments to the .mli file, but this splits the documentation across two files unnecessarily.

Is this rendering behaviour intentional?

[jonludlam]

Thanks @craigfe - good timing, I'm just working on this right now - I'll get back with findings!

[lpw25]

This behaviour is deliberate. The top-level comment in a module type or module is treated as a description of the module type or module itself. This is how you can have descriptions of top-level modules. In other words:

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

and

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

are equivalent. This behaviour is possibly unnecessary for non-top-level modules, so perhaps it should be removed. Or perhaps we should remove it for module types and keep it for modules.

Even if we removed that behaviour, you still wouldn't get the behaviour that you want with an _intf module type: you don't just
want the comment to be included in the resulting signature you want it to become the description comment for the module. For that I have previously suggested that we want a something stronger than @inline for _intf includes that doesn't only include the module contents inline but also treats the top-most comment as the description comment.

[lpw25]

I propose the following solution to this:

1. The first comment of a signature should be considered to be part of the signature itself, it should be stored separately from the other comments. By extension, expansions of a module type would have first comments.
2. A module's main documentation should be any comment attached to its definition followed by the first comment of its expansion.
3. A module type's main documentation should just be any comment attached to its definition.
4. A signature that starts with an @inline include before any doc comments gets the first comment of that include as its first comment.
5. All the above should apply similarly to class types and classes with respect to the first comment in a class signature.

This is mostly a change of behaviour for module type definitions, which would no longer get the first comment of their contents as part of their main documentation.

[Julow]

After doing some testing, here is the current behavior and what would change with @lpw25's suggestion:

(** c1 *)
module M : sig
  (** c2 *)

  ...
end

Currently:

• c1 is the doc of M and is rendered alongside M's declaration and inside M's page.
• c2 is rendered as a floating comment inside M, even when c1 is not present.

Changes:

• Both near M's declaration and inside M's page, c1 + c2 should be rendered.
• Keep the current behavior for module types

(** c1 *)
module type T = sig (* c2 *) ... end

(** c3 *)
module M : T

Currently:

• c3 is rendered near M.
• c3 and c2 (as a floating comment) are rendered inside M's page.
• c1 is not rendered around M.

This shouldn't change. This is the reason for not changing the behavior of module types in the first case.

(** c1 *)
module type T = sig (* c2 *) ... end

module M : sig
  include T (** @inline *)
end

Currently:

• c1 and c2 are not rendered near M.

Changes: Render c2 as the doc of M (both alongside M's declaration and inside M's page)

This doesn't apply if any of c3, c4 or c5 is present:

(** c3 *)
module M : sig
  (** c4 *)

  include T
    (** c5
        @inline *)
end

However, c2 should be rendered as a floating comment (the original issue)