-
Notifications
You must be signed in to change notification settings - Fork 217
Style suggestion: consistent placing of structure item doc comments #1010
Copy link
Copy link
Closed
Labels
Description
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:
- always put doc comments on structures before, regardless of the size of the structure.
- refine the size heuristic to account for potential multi-line functor parameters.
CC. @Julow
Reactions are currently unavailable