RFC: Raw, Non-Nesting Comment Syntax

language design
22

Added thoughts about whether to nest raw in classical block comments in OP.

Added regex to the examples answer.

24

I was specifically proposing that line comments should nest inside block comments, not anything else. I don't see why you would want comment delimiters to be active inside strings or vice versa; quite the reverse, there's probably any number of existing programs that do things like

let block_comment_start = "/*";
let block_comment_end = "*/";

and

/* The apostrophe in this comment doesn't indicate
   a character literal or lifetime */

(deleted and reposted with proper reply tagging)

25

The purpose of nesting block comments inside block comments is presumably so that you can comment out a block of Rust code containing such line comments.

For the same reason you might want commenting out a block of Rust code containing string literals to work:

/* commented out for now
let block_comment_end = "*/";
*/
26

Here's an alternative. What if we made the number of * meaningful for block comments?

Them you can add as many as you need to comment out the block in question. Usually this would be just one or two:

/**
let x = "something */";
**/

This would obviously be a breaking syntax change but it could be done across an edition.

3 Likes
27

/** **/ is already a doc comment.

2 Likes
28

True, you would have to change block doc comments to something else, maybe /*! or something.

Edit: oh wait that would be an inner comment.

29

/*! is the equivalent of #![doc already too.

30

Here's an alternative. What if we made the number of * meaningful for block comments?

…

True, you would have to change block doc comments to something else, maybe /*! or something.

I don't mind alternate solutions. But they shouldn't redefine existing syntax. All of /**, /*! as well as /* or */ after /* already have a meaning. Anything else inside of a comment is just that and shouldn't suddenly get meaning.

That's why I proposed new, currently invalid syntax (hence backwards compatible) on the outside of comments. And it aligns with comparable issues in strings. Except in strings it's only comfort, as you can always mask inner characters. Whereas in comments all the examples above are currently impossible to nest. So they cause surprising problems, when commenting out code.

2 Likes
31

OK, I see how you got there from what I said and I agree this is potentially just as troublesome, or more so, as line comments containing block comment boundary markers. I also agree we definitely don't want to start looking for strings nested inside block comments -- not only would that make parsing too complicated, I'm certain it would break existing code that has unpaired " characters inside comments. " has multiple uses in natural language text, some of them naturally unpaired -- ditto marks, leading " on multi-paragraph quotations, etc.

I'm still not convinced that looking for line comments inside block comments is a mistake. It seems inconsistent to me that we don't do that now but we do look for block comments inside block comments. (Honestly, I had no idea Rust allowed block comments to nest in the first place! After 25 years of C it would never have occurred to me to try it.)

What if dedicated syntax for commenting out syntactically correct code that looks like an item? Actually, don't we have this right now in the form of

// corrected, see next two posts
#[cfg(any())] mod comment_out {
  // ...
}

?

1 Like
32

#[cfg(false)] is an error (you can't use a keyword), but #[cfg(FALSE)] is fairly common to see and #[cfg(any())] is actually unsatisfiable (and also somewhat common). (I personally think true/false should be permitted with the obvious meaning in cfg tests.)

2 Likes
33

Yeah, after I wrote that I looked at the spec for cfg expressions and realized that it would need to be #[cfg(any())] at present. I agree with you that true and false should be allowed with the obvious meaning.

Still, my larger point stands: #[cfg(any())] mod x { ... } could be used here, basically as #if 0 ... #endif is used in C.

34

Ok, that's a way of ignoring a single item. But it doesn't deal with the woes (and impossibility) of commenting out arbitrary stretches of code. That's what RFC this is about. When juggling wiith related functions, I have even started a comment in the middle of one, up to the corresponding point in the other – though rarely so, admittedly.

35

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.