line comments delimiter

[const-rs]

Following the recent ideas in (ocaml pull-request discussion)[https://github.com/ocaml/ocaml/pull/671], I would like to propose another symbol for line comments - |*, since (*) conflicts with typical documentation generation tool like ocamldoc/haddock/doxygen.

Pro:

1. |* is easy to extend for smldoc - |**.
2. It is asymmetric, two character.
3. Stylistically it is close to (* comment *); the opening symbol | does not have a pair like [ or (; blocks of comments are naturally separated by vertical line from code:

fun f x = 8 +  |* intercept term
    (sin x) +  |* sin component
    (cos x) +  |* cos component
    (sqrt x)   |* this works only for x >= 0

3. It gives the same benefits as (* *) when commenting parts of the code. You need to add just one symbol to the right of pattern-matching or sum type declaration:

(* here we temporary comment out cos x with just two '*' *)
fun f x = 1.0 (*cos x*) 

datatype option a' = None
      | Some a'
      |* Unsure (* may be we will need this in the future? *)

Contra:

1. (*) is already in proposal.
2. |* is relatively hard to type compared to --, // or other common symbols.

[rossberg]

I came up with (*) originally because it was the only syntax I could think of that is backwards-compatible. In contrast, |* is a valid symbolic identifier today, so repurposing it is a breaking change. The same applies to pretty much any combination of symbols or symbols+brackets you can think of. The only reason (*) works is because (* already has special status.

[ratmice]

I really like ;; that was proposed in the linked thread (well i guess they proposed 3 semicolons),
2 was used in @rossberg 's 1ml, and the variant ;;;; comment to EOF, the only change there that I would consider is having ;;;; be whitespace significant so:

signature FOO = sig
;;;;
comment out stuff at the same indentation level, primarily useful for temporarily commenting
out code temporarily, like signature members
end
;;;; implicitly comment to EOF because we cannot indent lower than the beginning of the line.

I guess the issue is that the following is effectively allowed by existing compilers?
I will note that I don't see where in the grammar it is accepted, everything i saw treats semicolon as a sequence separator.

- val foo = 1;; val foo = 2;
val foo = 1 : int
val foo = 2 : int

[rossberg]

Semicolon is a declaration separator in SML, and for better or worse, declarations can be empty. So ;; is a legal program today, as is any other number of consecutive semicolons.

[ratmice]

@rossberg Thank you, I see it now, it took me quite a bit of staring before I noticed the empty declaration comment in figure 4/page 25, perhaps an empty optional <> on the left hand side would make it stand out more.

[JohnReppy]

Another argument against changing is that MLton and SML/NJ already implement the "(*)" syntax (not enabled by default though).