On Friday, 9 February 2018 at 09:48:14 UTC, Nick Sabalausky (Abscissa) wrote:
> On 02/09/2018 04:09 AM, Kagamin wrote:
>> On Friday, 9 February 2018 at 08:54:09 UTC, Timothee Cour wrote:
>>> * `/* */` should never be used
>> Not a single reason for that
> Except of course for the ones that have been pointed out. And for the reasons you yourself brought up in favor of version(none). Not a single reason aside from all of those.

If they can't be used in edge cases is not a reason to never use them.

>>> * properly nested `/+ +/` indeed don't cause issues
>> Disproved two times in this thread. Anyway nothing properly done causes issues.
>
> Being that the issues with /* */ are a superset of the issues with /+ +/, they clearly cause fewer issues than /* */.

The OP's example shows that nested comments ignore programmer's intent. In the end they work when opening and closing sequences are gotten right, not when programmer intends them to nest. The difference is so infinitesimal it's difficult to formulate it, but difference in complexity is evident.

On Friday, 9 February 2018 at 11:16:01 UTC, Nick Sabalausky (Abscissa) wrote:
> On 02/09/2018 05:31 AM, Kagamin wrote:
>> On Friday, 9 February 2018 at 09:42:46 UTC, Nick Sabalausky (Abscissa) wrote:
>>> Huh? So are you *pro-* or *anti-* heredoc?
>> I personally prefer python's triple quoted strings. Elegant, simple and enough for most stuff. That example only shows what D has.
>> version(none)q{ FOO }; is likely to work for most stuff too.
>
> /+ +/ is likely to work for most stuff, too.

So do /* */
It was only a minor problem for C89, because it had no line comments and people didn't know about #if 0

> I think version(none) has solidly proven that higher-level semantic code-disabling, while sounds like a great idea on paper, actually provides no practical, non-theoretical gains other than the ability to nest, which /+ +/ shares (along with the ability to be used in more scenarios and be less verbose).

I insert version(none) with just Ctrl+V which is faster and easier than any stream comment that requires you to jump back and forth to properly catch a bunch of raw characters. Also with it you can switch alternative implementations like
version(all)
  ...
else
  ...
If the code is not deleted, it's useful; if it's useful, it will be used; to be used it must be readable; to be readable it should be highlighted; to highlighted it shouldn't be a comment.

> /**
> Be sure to check the various files at extras/foo*/package.d
> and also: https://gcc.gnu.org/onlinedocs/libstdc++/faq.html
> */
>
> Unlike the "disabling code that contains the end-of-disabled-code token" stuff, THIS example isn't quite so trivial to deal with in a way that's reasonably readable from both the generated docs and from within the code itself.

/**
Be sure to check the various files at extras/foo.../package.d
and also: https://gcc.gnu.org/onlinedocs/libstdc++/faq.html
*/

Ok, somebody might be unable to come up with this, but people didn't know about #if 0 until told.

On Friday, 9 February 2018 at 11:16:01 UTC, Nick Sabalausky (Abscissa) wrote:
>
> /**
> Be sure to check the various files at extras/foo*/package.d
> and also: https://gcc.gnu.org/onlinedocs/libstdc++/faq.html
> */
>
> Unlike the "disabling code that contains the end-of-disabled-code token" stuff, THIS example isn't quite so trivial to deal with in a way that's reasonably readable from both the generated docs and from within the code itself.

How about

// Be sure to check the various files at extras/foo*/package.d
// and also: https://gcc.gnu.org/onlinedocs/libstdc++/faq.html

The good part of having multiple comment starters is that you can
pick the one that works best with a specific text you would
like to add as a comment.
// goes to the end of the line, so the text can be pretty much anything
(except for EOL of course), so is a good fallback.

On Friday, 9 February 2018 at 03:06:56 UTC, Timothee Cour wrote:
> and weird urls like https://gcc.gnu.org/onlinedocs/libstdc++/faq.html

Workaround: percent-encoding.

https://gcc.gnu.org/onlinedocs/libstdc%2B%2B/faq.html works too.

On Saturday, 10 February 2018 at 07:57:12 UTC, Vladimir Panteleev wrote:
> On Friday, 9 February 2018 at 03:06:56 UTC, Timothee Cour wrote:
>> and weird urls like https://gcc.gnu.org/onlinedocs/libstdc++/faq.html
>
> Workaround: percent-encoding.
>
> https://gcc.gnu.org/onlinedocs/libstdc%2B%2B/faq.html works too.

A real life example: http://clang.llvm.org/docs/UsersManual.html#mingw-w64
Well, it's just C++ causing trouble to everyone again.

On 2/8/2018 7:06 PM, Timothee Cour wrote:
> /"EOC
> This is a multi-line
> heredoc comment allowing
> /+ documented unittests containing nesting comments +/
> and weird urls like https://gcc.gnu.org/onlinedocs/libstdc++/faq.html
> EOS"/

There isn't any commenting scheme that won't trip you up with certain characters in the comments. I don't see a compelling case for adding another kind of comment.

Vladimir's suggestion to use %2B instead of + seems to resolve this adequately.

On Saturday, February 10, 2018 15:03:08 Walter Bright via Digitalmars-d wrote:
> On 2/8/2018 7:06 PM, Timothee Cour wrote:
> > /"EOC
> > This is a multi-line
> > heredoc comment allowing
> > /+ documented unittests containing nesting comments +/
> > and weird urls like https://gcc.gnu.org/onlinedocs/libstdc++/faq.html
> > EOS"/
>
> There isn't any commenting scheme that won't trip you up with certain characters in the comments. I don't see a compelling case for adding another kind of comment.
>
> Vladimir's suggestion to use %2B instead of + seems to resolve this adequately.

You could also always just declare a DDOC macro.

Just put

Macros:
    PLUS=+

in the ddoc comment and then use $(PLUS) instead of +. It's more verbose that way given that PLUS isn't one of the standard ddoc macros, but it's more idiomatic to look at.

- Jonathan M Davis

all these workarounds are rather ugly; the proposed syntax works all
the time (user can just pick a EOC token not in comment) and is analog
to existing D heredoc strings, so nothing surprising there.
Would PR's be accepted?


On Sat, Feb 10, 2018 at 5:01 PM, Jonathan M Davis via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> On Saturday, February 10, 2018 15:03:08 Walter Bright via Digitalmars-d wrote:
>> On 2/8/2018 7:06 PM, Timothee Cour wrote:
>> > /"EOC
>> > This is a multi-line
>> > heredoc comment allowing
>> > /+ documented unittests containing nesting comments +/
>> > and weird urls like https://gcc.gnu.org/onlinedocs/libstdc++/faq.html
>> > EOS"/
>>
>> There isn't any commenting scheme that won't trip you up with certain characters in the comments. I don't see a compelling case for adding another kind of comment.
>>
>> Vladimir's suggestion to use %2B instead of + seems to resolve this adequately.
>
> You could also always just declare a DDOC macro.
>
> Just put
>
> Macros:
>     PLUS=+
>
> in the ddoc comment and then use $(PLUS) instead of +. It's more verbose that way given that PLUS isn't one of the standard ddoc macros, but it's more idiomatic to look at.
>
> - Jonathan M Davis
>

On 2/10/2018 6:28 PM, Timothee Cour wrote:
> all these workarounds are rather ugly; the proposed syntax works all
> the time (user can just pick a EOC token not in comment) and is analog
> to existing D heredoc strings, so nothing surprising there.
> Would PR's be accepted?

You'll need to make a stronger case for it.

D already has 3 kinds of comments. You can pick a different kind if there are conflicting characters with one of them. Or use the mentioned escape methods.

On Saturday, February 10, 2018 18:53:03 Walter Bright via Digitalmars-d wrote:
> On 2/10/2018 6:28 PM, Timothee Cour wrote:
> > all these workarounds are rather ugly; the proposed syntax works all
> > the time (user can just pick a EOC token not in comment) and is analog
> > to existing D heredoc strings, so nothing surprising there.
> > Would PR's be accepted?
>
> You'll need to make a stronger case for it.
>
> D already has 3 kinds of comments. You can pick a different kind if there are conflicting characters with one of them. Or use the mentioned escape methods.

Personally, the _only_ time that I have ever had a problem with D's nested comments is when I was working on a lexer. I was forced to use version none when commenting out code that involved nested comments - especially the unit tests for malformed comments.

In general, nested comments just work perfectly. So, while dealing with the rare cases where they're a problem may be annoying, it's just not the sort of thing that most code has to worry about. And it's already kind of silly that we have as many comment types as we do.

- Jonathan M Davis