Feature request: Support the same formatting on non-doc-comments as is supported in doc-comments

[ELLIOTTCABLE]

Is your feature request related to a problem? Please describe. At the moment, ocamlformat tends to mangle comments like the following:

  (* We need

     - [E.builtin_dot] for javascript builtin
     - [E.mldot] *)

Describe the solution you'd like Since these are already handled nicely in the case of doc-comments ((** ... *)), it'd be nice if a single "comment language" was supported across the codebase — i.e. formatting that is passed-thru safely when there's a doc-comment, would be passed-thru identically in a non-doc-comment in an implementation file.

[jberdine]

The catch with docstrings is that they have to parse correctly. For general comments, what to do in the case that it doesn't parse as a docstring needs to be decided. I expect that it isn't feasible to require that all comments parse correctly as docstrings. It might also be irritating if when you make a typo in a comment, it causes it to not parse as a docstring, and then gets mangled. This is already somewhat the case with banner comments, where if the *s don't quite line up vertically, then ocamlformat mangles the comment. But it's easier to see that that will happen than to guess if the comment will parse as a docstring. Are there other ideas about the desired UI in the case of unparsable comments?

[ELLIOTTCABLE]

Hmmmm. I don't know if I'm the person to ask; I'm biased, of course, but I think this would be reasonable:

1. v0.14.3: Add an option to --parse-all-comments or similar; when used, throw hard error and fail out when parsing fails;
2. v0.15: Support --no-parse-all-comments; promote --parse-all-comments to the default, but instead of hard-erroring, fallback to the old behaviour upon parse-failure, and report a non-fatal warning to the user
3. v0.16: Promote hard-error to the default behaviour, possibly eventually deprecate --no-parse-all-comments, if it doesn't get a lot of usage across GitHub or whatnot.

Basically, my primary concern here is just usability / comprehensibility to those new to the language. Doc-comments being first-class in OCaml is not something that is likely to change, or that I much wish to campaign against personally; but I feel this behaviour is a stumbling-block to newbies to the language / new contributors to a project using ocamlformat. Simplifying the apparent behaviour and constraining obscure / un-user-friendly features seems very in-scope for an autoformatter; so I hope this is up the alley of what we want to do here!

[jberdine]

We're going to keep supporting formatting code that has some code commented out, so parsing all non-docstring comments as docstrings and failing if they don't parse isn't a long-term destination.

I acknowledge the fact that docstrings being different from other comments trips up newcomers (and many not-so-newcomers to be fair): I have seen many many instances of non-docstrings used where they should be docstrings. I also agree that there are cases where you want to write a formatted comment somewhere that a docstring is not allowed. What I'm not sure about is whether that means that docstrings should be allowed in more places, or whether the formatter should confuse the two together. I think that we have to keep in mind that there are other consumers of docstrings, e.g. documentation generators, and that making the distinction between comments and docstrings less clear makes it less clear to programmers what ends up in the documentation and what doesn't.

Setting aside alternatives that require changing the OCaml language, what we currently have are

1. docstring-comments that should parse into a structured form, but have the constraint that they may only appear in certain contexts; and
2. "normal" comments that have free-form content and can appear anywhere.

Perhaps we need a third option that can appear anywhere like normal comments but are expected to parse as a docstring (just to have one format) and will be auto-formatted as such.

I expect that we could find some magic first character to use to distinguish these from normal comments, such as (*^ blah *). Do you think that would be satisfactory?

[ELLIOTTCABLE]

I don't know how I missed this response, but I would absolutely love that, personally.

That said, I'm not at all sure what the userbase for such a feature would be besides me, so I'm not sure if it's worth the maintenance burden …

May I suggest (*= This? I feel the `=` implies formatting *) a bit better.