Hi!
According to the OCamls-syntax …
“Comments are introduced by the two characters (*, with no intervening blanks, and terminated by the characters *), with no intervening blanks. Comments are treated as blank characters. Comments do not occur inside string or character literals. Nested comments are handled correctly.”
… there is nothing that speaks against having double quotes within them. Actually, you can have them, but only in even numbers.
So
(* This is a "good" comment *)
passes, but
(* Never use an odd number of " in your comment *)
will fail.
I stumbled over this when writing a comment and the meaning of " vs. '.
Simply put, a comment starts with (* and ends with *), except …
And it doesn’t help to try to escape with ".
Puzzled!
Edit: Funny enough, even the forum software tries to put meaning and interpretation into comments.
If there is a " character outside a string, it is starting a string literal. So you can’t have a comment there. In other words, a string literal ‘takes precedence’ over a comment.
As you quoted, “Comments do not occur inside a string.”
In the case shown, the string occurs within a comment. That is a different case, the inverse of the definition.
What the definition refers to is something like this:
let str = "This is not (* I mean "really" not *) allowed" in ...
With this example, I might have opened an other can of worms. Looks like no.
Just replace the really with a ^ and you get what you wrote or might have wanted. Or at least, the parser doesn’t complain about really. And that is expected behaviour.
A string starts an expression, that is terminated by a double quote. If you need a double quote within a string, you have to escape it. And if you write a comment within a string, it is not a comment, it is part of the string. As expected.
I’m expecting the same behaviour for comments. They end with a *). And you can even nest them (great). A comment is just that, nothing of the parser’s concern. It starts where it starts and ends where it ends. OCamldoc uses some markup, but that doesn’t change anything about the fact that it is a comment.
Also, where does the documentation state that strings can start within comments? And if so, what does the parser do with that random string? And how will it handle the end of the string?
(* Comment with some new "kind of statement" *)
Is that parsed and to what does it evaluate? Does it have to have proper syntax? Let’s see:
let str = (* comment "string" comment *);;
syntax error, as expected. So I see no “precedence” of a string over a comment.
Strings have to be closed, even if they appear in comments: this restriction allows arbitrary code to be commented properly. For instance, suppose you want to comment the following code:
print_endline "*)"
The commented version will be:
(* print_endline "*)" *)
There is an occurrence of *) inside the comment, which is ignored because it occurs inside a string.
Similarly, in the following comment, the first occurrence of *) is ignored as it occurs inside a string.
(* Never use an odd number of " in your comment *)"*)
OK, thanks for that accademic example.
Here is the solution if OCaml would ignore double quotes.
(* `(* Never use an odd number of " in your comment *)" *)`
With syntax highlighting, one would immediately see where the problem is. Or the compiler would complain right at that spot.
So the standard should be corrected to add something like:
Comments may only contain an even number of double quotes
and give your example as an explanation.
Anyhow, I consider this as an examble of over-thinking without providing a solution to use a single double quote in a comment.
Here is how I stumbled into this pitfall:
This is a comment: Attribute values might be enclosed in pairs of ’ or ".
