Question: What does wrap-comments do?

[mbarbin]

This is a question about the formatting option wrap-comments=true.

I think I am misunderstanding its intent. I thought this would be an option to force inserting newline characters in regular non-docstring comments, so they fit into the margin. However, experimenting with this, this doesn't seem to be the case. I am not sure whether I should file a bug report, or I misunderstood how the option can be used.

Here is my config:

version = 0.27.0
profile = janestreet
wrap-comments = true

Here was an attempt at writing a long comment, with the hope that it would be automatically wrapped on fmt:

(* Hello, this file has [wrap-comments = true] enabled via its [.ocamlformat] config, but I am not sure what changes does it make. This comment for example is not wrapped when this file is formatted. Sounds like the setting is ignored. Or how long should a comment for it to be wrapped? I am keeping this comment here for the time being to monitor whether there'd be changes on this front. *)

[Julow]

This changed in #2371. Regular comments are formatted as doc-comments with the janestreet profile, independently of the wrap-comments option. But then, because parse-docstrings is not enabled, the comments are not formatted. There seems to be a logical problem here.
An other thing is that doc-comments don't wrap with the janestreet profile, and that cannot be changed with an option.
I may have fixed that in #2645

[mbarbin]

Thank you for looking into the issue!

Asterisk

I built a local version of ocamlformat including this fix:

$ ocamlformat --version
0.27.0-1-g4c94d48

and then tried it out with this config:

version=0.27.0-1-g4c94d48
ocaml-version=5.2
profile=janestreet
parse-docstrings=true
wrap-comments=true

I confirm now that a file like the following is stable through fmt. Thank you!

(* Hello.
 * This is a comment with asterisk chars
 * at the beginning of every lines.
 *
 * Yay!
 *)
let () = ()

Incidentally as I was editing the file manually, I came across this case:

(* Hello.
   * This is a comment with asterisk chars
 * at the beginning of every lines.
 *
 * Yay!
 *)
 let () = ()

$ ocamlformat mini_fmt.ml
ocamlformat: Cannot process "mini_fmt.ml".
  Please report this bug at https://github.com/ocaml-ppx/ocamlformat/issues.
  BUG: comment changed.
File "mini_fmt.ml", lines 1-6, characters 0-3:
Error: comment (*  Hello.
   * This is a comment with asterisk chars
 * at the beginning of every lines.
 *
 * Yay!
  *) dropped.
  BUG: comment changed.
File "mini_fmt.ml", lines 1-6, characters 0-2:
Error: comment (*  Hello.
   * This is a comment with asterisk chars
   * at the beginning of every lines.
   *
   * Yay!
 *) added.

As in, if the asterisk are not originally aligns, something unexpected happens. Reporting for your consideration. cours Asterixme, cours!!

Wrap-comments

I then tried to copy my long one line comment in another file, both as regular or doc-strings comment. I does not wrap.

An other thing is that doc-comments don't wrap with the janestreet profile, and that cannot be changed with an option.

I am not sure if the current fix intended to fix this as well. If it did, something is not working as expected.

[mbarbin]

Hello @Julow just wanted to make sure you see my last comment after the issue is closed. It sounds like it's missing another round of fixes for this and #2643

By the way I have tried the wrap-comments option with the conventional profile to get some experience with it, and I found it very nice. I look forward to using it with my current config. Thank you.

[Julow]

Thanks for your help :) I'll re-open the issue as a bug with asterisks is still here.

An other thing is that doc-comments don't wrap with the janestreet profile, and that cannot be changed with an option.

I am not sure if the current fix intended to fix this as well. If it did, something is not working as expected.

The fix was not intended to change this as that's the style used at Janestreet. One possibility would be to expose this as an option.

@tdelvecchio-jsc OCamlformat avoids wrapping paragraphs in comments when using the Janestreet profile. Is this intended or is this a workaround for something that could be improved ?

[mdelvecchio-jsc]

This is something @dvulakh is currently working on.