Skip to content

Style suggestion: consistent placing of structure item doc comments #1010

@craigfe

Description

@craigfe

What is the reason for this new style?
Inconsistency surrounding doc comments and signatures. Consider the following example:

(** This comment goes before *)
module S_ext : sig
  type t
end

module Index : Index.S
(** This one goes after *)

module Index2
    (Paramater_module : BAR_LONG_MODULE_TYPE_NAME)
    (Foo : BAR)
    (Foo : BAR)
    (Foo : BAR)
    (Foo : BAR)
    (Foo : BAR) : sig end
(** This one _still_ goes after *)

module Make (Config : sig
  val blah : string

  (* this could be a really long signature *)
end) : S
(** Doc comment still goes after *)

With profile=conventional, Ocamlformat will try to put structure doc comments after the struct by default (presumably to keep symmetry with the value signatures). When the structure is too large, it will instead put the comment at the start. I like this behaviour; however, it isn't consistent about this w.r.t. functors whose parameters span multiple lines.

Describe the solution you'd like
I see two solutions:

  1. always put doc comments on structures before, regardless of the size of the structure.
  2. refine the size heuristic to account for potential multi-line functor parameters.

CC. @Julow

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions