Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Jacob Carlborg via Digitalmars-d]

On 2018-02-12 23:35, Walter Bright wrote:


The last dstep commit was November 2017.


Yes? I've been working on a separate branch lately


I take it dstep spawns the clang compiler?


No, it uses libclang, i.e. using the Clang compiler as a library.

--
/Jacob Carlborg

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Kagamin via Digitalmars-d]

On Tuesday, 13 February 2018 at 04:44:27 UTC, timotheecour wrote:

Try to comment that with `/* */`:
```
void drawCircle(int angle /* in degrees */);
```


When you want to disable whole declaration, version(none) works 
just fine.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[timotheecour via Digitalmars-d]

On Tuesday, 13 February 2018 at 04:16:22 UTC, Nick Sabalausky 
(Abscissa) wrote:

On 02/09/2018 07:11 AM, Kagamin wrote:
On Friday, 9 February 2018 at 11:16:01 UTC, Nick Sabalausky 
(Abscissa) wrote:

On 02/09/2018 05:31 AM, Kagamin wrote:

version(none)q{ FOO }; is likely to work for most stuff too.


/+ +/ is likely to work for most stuff, too.


So do /* */


Seriously, are you trying to troll? (Not rhetorical, genuinely 
wondering.)


No. No, /* */ isn't likely to work with most stuff. Not in any 
codebase that actually USES /* */. Not without it being granted 
nestability. And no, I'm not talking theoretically or 
speculating here, this is speaking from years of direct 
experience on codebases that use /* */.


here's the canonical example where `/* */` fails:

Try to comment that with `/* */`:
```
void drawCircle(int angle /* in degrees */);
```

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Nick Sabalausky (Abscissa) via Digitalmars-d]

On 02/09/2018 07:11 AM, Kagamin wrote:
On Friday, 9 February 2018 at 11:16:01 UTC, Nick Sabalausky (Abscissa) 
wrote:

On 02/09/2018 05:31 AM, Kagamin wrote:

version(none)q{ FOO }; is likely to work for most stuff too.


/+ +/ is likely to work for most stuff, too.


So do /* */


Seriously, are you trying to troll? (Not rhetorical, genuinely wondering.)

No. No, /* */ isn't likely to work with most stuff. Not in any codebase 
that actually USES /* */. Not without it being granted nestability. And 
no, I'm not talking theoretically or speculating here, this is speaking 
from years of direct experience on codebases that use /* */.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Walter Bright via Digitalmars-d]

On 2/12/2018 12:23 PM, Jacob Carlborg wrote:

Here you go [1]. It's a bit outdated now, from 2013, but it worked back then.


The last dstep commit was November 2017.



[1] 
https://github.com/jacob-carlborg/dmd/commit/2837d340c065cc2bf3f0a83cb96c4d9f22fb3a30 


I take it dstep spawns the clang compiler?

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[David Nadlinger via Digitalmars-d]

On Monday, 12 February 2018 at 22:35:23 UTC, Walter Bright wrote:

I take it dstep spawns the clang compiler?


It embeds the Clang frontend, which is designed to be usable as a 
library.


 — David

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Walter Bright via Digitalmars-d]

On 2/12/2018 8:25 AM, Patrick Schluter wrote:

C is currently at [C11].

[C11]: https://en.wikipedia.org/wiki/C11_%28C_standard_revision%29


Yes, you're right. I haven't paid any attention to C11 :/

The array bounds checking interface,

http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1969.htm

is just sad. The one I proposed would actually work:

https://digitalmars.com/articles/b44.html

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Jacob Carlborg via Digitalmars-d]

On 2018-02-12 02:27, Walter Bright wrote:


Know what is a heavyweight problem worth our while? Having dmd be able
to directly read C .h files, so the poor user does not have to manually
translate them.

We've already got a huge chunk of that problem solved. The Digital Mars
C/C++ front end is now Boost licensed. It can be used. It's already been
converted to D! The preprocessor in it is a bit dated and a bit too
specific to Windows - but we've got Warp now!

Replace the preprocessor in dmc++ with Warp, slice off the back end, and
make it a module that dmd can import.

Wouldn't it be nice to support:

 import stdio.h;// Look, Ma! C headers!

There are some intractable issues, and it may be impossible to get 100%
to "it just works", but looking past that it might be a huge win for us.


Here you go [1]. It's a bit outdated now, from 2013, but it worked back 
then.


[1] 
https://github.com/jacob-carlborg/dmd/commit/2837d340c065cc2bf3f0a83cb96c4d9f22fb3a30


--
/Jacob Carlborg

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Patrick Schluter via Digitalmars-d]

On Monday, 12 February 2018 at 03:17:20 UTC, Walter Bright wrote:

On 2/11/2018 6:26 PM, Elie Morisse wrote:

Wow, you converted DMC++'s front-end to D?


Yes, it's just frustrating for me to work on C++ code anymore. 
:-)


To chime in on that, Calypso i.e the LDC+Clang equivalent of 
what you described isn't dead (it just revived a few weeks ago 
from a long slumber) and it should be possible to make a 
smaller codegen-less version for DMD that only depends on a 
few Clang and LLVM support libraries. Another possibility..


Good ideas! Some things to consider:

1. I'd like this to be pluggable, so that different compilers 
can be used without being disruptive to dmd.


2. DMC++ is not only a C compiler, but a C++ compiler. The C++ 
compiler, though, is stuck on C++98 and is unlikely to see much 
improvement on that.


3. BetterC is called BetterC and not BetterC++ because D's C++ 
interop is more fragile than the C interop. I felt it better to 
nail the C end first.


4. It certainly would be nice to be able to insert C++ headers, 
too, but I'd expect more problems (!).


5. C is stuck at C99. Being a fixed target makes it more 
tractable. Supporting C++ means constant revisions and high 
support costs.


C is currently at [C11]. Granted not many projects switched to 
it, as its changes were not as useful as C99. All the things 
added to C11 are features that try to extend the language in 
directions where it's better to switch to a better language like 
D (-betterC).


6. Using DMC++ as a front end would add somewhat less than a 
megabyte (half?) to the binary size of dmd. I have no idea what 
Calypso or other solutions would add. If they are large, they 
may only make sense as a separate executable as a filter.


[C11]: https://en.wikipedia.org/wiki/C11_%28C_standard_revision%29

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Walter Bright via Digitalmars-d]

On 2/11/2018 8:59 PM, Nick Sabalausky (Abscissa) wrote:
Though I do realize that's not likely to happen. It's not as if I'm saying "hey, 
go do this". All I'm really saying is "I like this idea, I'm in favor of it, and 
it's worth being open to." Not much more than that.


> "That's a reasonable point and a would be a nice touch, and it doesn't impact 
> other things. Andrei and I, naturally, can't dedicate any of our resources to 
> it because we have more crutial priorities on our plates, but we wouldn't

> necessarily veto a quality implementation."

It has nothing to do with my or Andrei's time, nor anything to do with whether 
it is a quality implementation or not.


We should not be adding features just because we can. They need a compelling 
case. This one does not have one. If such a case does emerge in the future, we 
can look at it again.


I do not wish to tacitly greenlight projects that have little chance of being 
incorporated. It isn't right to waste peoples' time like that. I don't derive 
any pleasure from being Dr. No, but somebody has to do it, and it falls to me.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Nick Sabalausky (Abscissa) via Digitalmars-d]

On 02/11/2018 08:27 PM, Walter Bright wrote:

On 2/11/2018 5:05 PM, Nick Sabalausky (Abscissa) wrote:
That's the same exact reason most languages don't have most of the 
nice things in D, like separators for numeric literals: Because 
they're not strictly necessary. But if D had never been willing to 
improve the state of the art by not being afraid of "not stricktly 
necessary" features, very few of us would have ever had reson to come 
onboard with D in the first place. And yes, I know D's not at that 
point any more. And that's one of my biggest dissapointments with D.


D is already a very large language. There's got to be a point where some 
pruning makes for a better language. Adding more and more lightweight 
features for 0.1% use cases when we neglect heavyweight features for 30% 
use cases is not where we should be shooting our arrows.


Know what is a heavyweight problem worth our while? Having dmd be able 
to directly read C .h files, so the poor user does not have to manually 
translate them.


We've already got a huge chunk of that problem solved. The Digital Mars 
C/C++ front end is now Boost licensed. It can be used. It's already been 
converted to D! The preprocessor in it is a bit dated and a bit too 
specific to Windows - but we've got Warp now!


Replace the preprocessor in dmc++ with Warp, slice off the back end, and 
make it a module that dmd can import.


Wouldn't it be nice to support:

     import stdio.h;    // Look, Ma! C headers!

There are some intractable issues, and it may be impossible to get 100% 
to "it just works", but looking past that it might be a huge win for us.


And, let's not forget working on ref counting.


Definitely all very cool stuff, no argument here. But for smaller things 
it would still be nice to hear something closer to:


"That's a reasonable point and a would be a nice touch, and it doesn't 
impact other things. Andrei and I, naturally, can't dedicate any of our 
resources to it because we have more crutial priorities on our plates, 
but we wouldn't necessarily veto a quality implementation."


instead of:

"It's not one of the big-picture items for D therefore it doesn't belong 
in D"


Though I do realize that's not likely to happen. It's not as if I'm 
saying "hey, go do this". All I'm really saying is "I like this idea, 
I'm in favor of it, and it's worth being open to." Not much more than that.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Walter Bright via Digitalmars-d]

On 2/11/2018 6:26 PM, Elie Morisse wrote:

Wow, you converted DMC++'s front-end to D?


Yes, it's just frustrating for me to work on C++ code anymore. :-)

To chime in on that, Calypso i.e the LDC+Clang equivalent of what you described 
isn't dead (it just revived a few weeks ago from a long slumber) and it should 
be possible to make a smaller codegen-less version for DMD that only depends on 
a few Clang and LLVM support libraries. Another possibility..


Good ideas! Some things to consider:

1. I'd like this to be pluggable, so that different compilers can be used 
without being disruptive to dmd.


2. DMC++ is not only a C compiler, but a C++ compiler. The C++ compiler, though, 
is stuck on C++98 and is unlikely to see much improvement on that.


3. BetterC is called BetterC and not BetterC++ because D's C++ interop is more 
fragile than the C interop. I felt it better to nail the C end first.


4. It certainly would be nice to be able to insert C++ headers, too, but I'd 
expect more problems (!).


5. C is stuck at C99. Being a fixed target makes it more tractable. Supporting 
C++ means constant revisions and high support costs.


6. Using DMC++ as a front end would add somewhat less than a megabyte (half?) to 
the binary size of dmd. I have no idea what Calypso or other solutions would 
add. If they are large, they may only make sense as a separate executable as a 
filter.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Walter Bright via Digitalmars-d]

On 2/11/2018 5:43 PM, timotheecour wrote:
It doesn't leave anything in Ddoc either, so that's not a viable workaround if 
that comment is intended to be a DDoc.


You're right that this will never be intrepreted as a Ddoc comment. But I infer 
that this resolves the non-Ddoc case?


As for Ddoc comments, your proposed syntax does not contain a trigger for Ddoc, 
and Ddoc already allows for multiple forms of escapes. It's hard to see where it 
would be useful for Ddoc - keep in mind that Ddoc has its own syntax and triggers.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Elie Morisse via Digitalmars-d]

On Monday, 12 February 2018 at 01:27:19 UTC, Walter Bright wrote:

On 2/11/2018 5:05 PM, Nick Sabalausky (Abscissa) wrote:
Know what is a heavyweight problem worth our while? Having dmd 
be able to directly read C .h files, so the poor user does not 
have to manually translate them.


We've already got a huge chunk of that problem solved. The 
Digital Mars C/C++ front end is now Boost licensed. It can be 
used. It's already been converted to D! The preprocessor in it 
is a bit dated and a bit too specific to Windows - but we've 
got Warp now!


Replace the preprocessor in dmc++ with Warp, slice off the back 
end, and make it a module that dmd can import.


Wouldn't it be nice to support:

import stdio.h;// Look, Ma! C headers!

There are some intractable issues, and it may be impossible to 
get 100% to "it just works", but looking past that it might be 
a huge win for us.


Wow, you converted DMC++'s front-end to D?

To chime in on that, Calypso i.e the LDC+Clang equivalent of what 
you described isn't dead (it just revived a few weeks ago from a 
long slumber) and it should be possible to make a smaller 
codegen-less version for DMD that only depends on a few Clang and 
LLVM support libraries. Another possibility..

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[timotheecour via Digitalmars-d]

On Monday, 12 February 2018 at 01:27:19 UTC, Walter Bright wrote:
Know what is a heavyweight problem worth our while? Having dmd 
be able to directly read C .h files, so the poor user does not 
have to manually translate them.


read directly C++ header files instead of C .h files is what we 
should aim for. https://github.com/Syniurge/Calypso/ is actually 
already doing just that and already works in many situations (eg 
opencv).


Replace the preprocessor in dmc++ with Warp, slice off the back 
end, and make it a module that dmd can import.


Wouldn't it be nice to support:

import stdio.h;// Look, Ma! C headers!

There are some intractable issues, and it may be impossible to 
get 100% to "it just works", but looking past that it might be 
a huge win for us.


llvm+clang is a much better approach, guaranteeing compatibility 
with not just C but also and especially C++ (including current 
and future C++ standards). Calypso already understands C++ 
templates, C++ exceptions, can return C++ classes by value (not 
just by reference), without the restrictions imposed on 
extern(C++) classes/structs.


```
modmap (C++) "opencv2.hpp";
import (C++) cv.Mat;
// can now use C++ templates, functions, macros etc in D code.
```

There are of course a number of issues left to be ironed out, but 
it's a much more promising direction than restricting ourselves 
to C (as done with `cgo` for go). That's where we should focus 
our efforts as far as interop is concerned.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[timotheecour via Digitalmars-d]

On Monday, 12 February 2018 at 01:39:31 UTC, Walter Bright wrote:

Easy:

mixin template comment(string s) { }

mixin comment!q"EOS
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";

It doesn't leave anything in the object file, either.


It doesn't leave anything in Ddoc either, so that's not a viable 
workaround if that comment is intended to be a DDoc.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Walter Bright via Digitalmars-d]

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"/


Easy:

mixin template comment(string s) { }

mixin comment!q"EOS
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";

It doesn't leave anything in the object file, either.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Walter Bright via Digitalmars-d]

On 2/11/2018 5:05 PM, Nick Sabalausky (Abscissa) wrote:
That's the same exact reason most languages don't have most of the nice things 
in D, like separators for numeric literals: Because they're not strictly 
necessary. But if D had never been willing to improve the state of the art by 
not being afraid of "not stricktly necessary" features, very few of us would 
have ever had reson to come onboard with D in the first place. And yes, I know 
D's not at that point any more. And that's one of my biggest dissapointments 
with D.


D is already a very large language. There's got to be a point where some pruning 
makes for a better language. Adding more and more lightweight features for 0.1% 
use cases when we neglect heavyweight features for 30% use cases is not where we 
should be shooting our arrows.


Know what is a heavyweight problem worth our while? Having dmd be able to 
directly read C .h files, so the poor user does not have to manually translate them.


We've already got a huge chunk of that problem solved. The Digital Mars C/C++ 
front end is now Boost licensed. It can be used. It's already been converted to 
D! The preprocessor in it is a bit dated and a bit too specific to Windows - but 
we've got Warp now!


Replace the preprocessor in dmc++ with Warp, slice off the back end, and make it 
a module that dmd can import.


Wouldn't it be nice to support:

import stdio.h;// Look, Ma! C headers!

There are some intractable issues, and it may be impossible to get 100% to "it 
just works", but looking past that it might be a huge win for us.


And, let's not forget working on ref counting.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Nick Sabalausky (Abscissa) via Digitalmars-d]

On 02/10/2018 06:03 PM, Walter Bright wrote:


There isn't any commenting scheme that won't trip you up with certain 
characters 


That's exactly the whole point of heredocs ever existing in the first 
place, its exactly the problem they're created for.


in the comments. I don't see a compelling case for adding 
another kind of comment.




That's the same exact reason most languages don't have most of the nice 
things in D, like separators for numeric literals: Because they're not 
strictly necessary. But if D had never been willing to improve the state 
of the art by not being afraid of "not stricktly necessary" features, 
very few of us would have ever had reson to come onboard with D in the 
first place. And yes, I know D's not at that point any more. And that's 
one of my biggest dissapointments with D.


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


Only for URLs. "URLs" was just one example of a language that can leas 
to trouble.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Martin Tschierschke via Digitalmars-d]

On Friday, 9 February 2018 at 03:06:56 UTC, Timothee Cour wrote:
same exact idea as motivation for delimited strings 
(https://dlang.org/spec/lex.html#delimited_strings)


```

auto heredoc = q"EOS
This is a multi-line
heredoc string
EOS"
;

/"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"/

```
I thought about it,  what if you define, that the /+  +/ comment, 
is not started by
'/+'  alone but by '/+ ' that means that the char behind the plus 
defines the ending of the comment.

So that /+my_special_block  has to end with  my_special_block+/
And '/+ '  with ' +/' where all whitespace characters should be 
allowed (\newline \tab \space).


I know that this might be a somehow breaking change, but it would 
not require a totally different kind of syntax.

And the mentioned URL-Strings lib++/  will not match for '/+ ' .
Would be interesting how often people write /+directly followed 
by the comment, without a space or the same at the end+/

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[ag0aep6g via Digitalmars-d]

On 02/11/2018 09:32 AM, Vladimir Panteleev wrote:

This syntax is syntactically ambiguous.

[...]

     assert(StringNumber("4")/"2" == "2"); // Conflict!
     // Division by string, or nested comment?


Strictly, it's not worse than `/*`, is it?


assert(4/*(new int(2)) == 2);
// Division by dereferenced pointer or comment?


I.e., it's a comment and you have to add a space to make it division.
But `/"` would break existing code, of course.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Vladimir Panteleev via Digitalmars-d]

On Friday, 9 February 2018 at 03:06:56 UTC, 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"/


This syntax is syntactically ambiguous.

struct StringNumber
{
string s;
string opBinary(string op)(string b)
{
import std.conv;
return mixin(`(this.s.to!long ` ~
op ~ ` b.to!long).to!string`);
}
}

unittest
{
assert(StringNumber("4")+"2" == "6");
assert(StringNumber("4")-"2" == "2");
assert(StringNumber("4")*"2" == "8");
assert(StringNumber("4")/"2" == "2"); // Conflict!
// Division by string, or nested comment?
}

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Vladimir Panteleev via Digitalmars-d]

On Sunday, 11 February 2018 at 01:01:21 UTC, Jonathan M Davis 
wrote:

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.


This won't work because URL linkification happens before macro 
resolution, so $(PLUS) will break URLs. But you can of course 
always use $(HTTP ...) or equivalent to emit a link explicitly.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Walter Bright via Digitalmars-d]

On 2/10/2018 7:27 PM, Jonathan M Davis wrote:

And it's already kind of silly
that we have as many comment types as we do.


Even more comment types implies we don't know what we're doing :-(

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Jonathan M Davis via Digitalmars-d]

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

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Walter Bright via Digitalmars-d]

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.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Timothee Cour via Digitalmars-d]

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
 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
>

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Jonathan M Davis via Digitalmars-d]

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

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Walter Bright via Digitalmars-d]

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.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Kagamin via Digitalmars-d]

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.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Vladimir Panteleev via Digitalmars-d]

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.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Dominikus Dittes Scherkl via Digitalmars-d]

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.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Kagamin via Digitalmars-d]

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.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Kagamin via Digitalmars-d]

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.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Nick Sabalausky (Abscissa) via Digitalmars-d]

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.

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). In real-world use, the only thing all 
that "smart" lexical processing done by version(none) accomplishes is to 
*create* new scenarios where the compiler says "Nope, disabling that 
code like that doesn't work for me. Try again."



But ok, that works, unless the code contains `EOS"`.
The very fact that I invented that just for this thread is evidence that 
it's not a rampant issue.


Ditto to code containing +/

As for the OP however, the question isn't how frequent, but what can be 
done when it does occur. All of our trouble scenarios with disabling 
blocks of code can be dealt with fairly cleanly and easily (although 
moreso with /+ +/ than version(none) IMO). But the doccomment scenarios 
brought up aren't so simple to deal with:


/**
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.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Nick Sabalausky (Abscissa) via Digitalmars-d]

On 02/09/2018 04:48 AM, Kagamin wrote:
On Friday, 9 February 2018 at 09:34:01 UTC, Nick Sabalausky (Abscissa) 
wrote:
Comments don't respect even lexical structure of commented code that 
you expect, version(none) does.


Uhh, you do know that IS nesting, right?


It's not a comment though, it disables code on semantic level way above 
raw character stream level, that's why it works better, also it's often 
one liner.




You seem to keep going back and forth on whether you like nesting or 
consider it a mistake. Hard to keep up.



And is far less widely supported by editors?


If you want it be bound to a shortcut, many text editors support 
invocation of external tools or text snippet expansion.


I meant syntax highlighting. I've given up on binding the 
comment/uncomment mechanism I want to key shortcuts: Dealt with too many 
editors that have too much trouble with something that should be so 
simple, wheras just plain typing works in nearly any editor. Which is 
all the more reason I don't use version(none) to disable code.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Kagamin via Digitalmars-d]

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.


But ok, that works, unless the code contains `EOS"`.
The very fact that I invented that just for this thread is 
evidence that it's not a rampant issue.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Jonathan M Davis via Digitalmars-d]

On Friday, February 09, 2018 08:42:08 Kagamin via Digitalmars-d wrote:
> On Friday, 9 February 2018 at 07:04:26 UTC, Nick Sabalausky
>
> (Abscissa) wrote:
> > (If I were in change of the world, /** and /* both would be
> > compiler errors, banned from all commits, and non-nesting block
> > comments of all types would be prohibited from all langauges
> > upon pain of...well, pain. They are spawn of satan and should
> > never exist.)
>
> Nested comments are superficial though, they were a mistake,
> really.

Seriously? Nested comments are _awesome_. IMHO, if anything, the fact that
the language has /* */ and /** */ is what's terrible. It makes sense for
porting code, but in all respects, they are worse than /+ +/ and /++ +/. I
hate it when I'm working in languages other than D and am forced to use
/* */ and deal with the fact that they don't nest. It may be a small thing,
but the fact that D has nested comments is just one more thing on the list
of things that add up to make D a lot more pleasant to work with than other
languages.

- Jonathan M Davis

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Kagamin via Digitalmars-d]

On Friday, 9 February 2018 at 09:34:01 UTC, Nick Sabalausky 
(Abscissa) wrote:
Don't see how that's remotely as common as "*/" in a 
C-style-comments codebase or commenting out something at the 
sub-statement level, like a function argument, type modifier or 
sub-expression, but hey, I guess if you have instances of that 
all over most functions in your codebase, then, yea, I guess 
disabling code with /+ +/ would be pretty nasty.


I have a few subexpression comments due to language bugs, so 
function signatures are temporarily changed, it's just 
version(none) never failed for me.


Comments don't respect even lexical structure of commented 
code that you expect, version(none) does.


Uhh, you do know that IS nesting, right?


It's not a comment though, it disables code on semantic level way 
above raw character stream level, that's why it works better, 
also it's often one liner.



And is far less widely supported by editors?


If you want it be bound to a shortcut, many text editors support 
invocation of external tools or text snippet expansion.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Nick Sabalausky (Abscissa) via Digitalmars-d]

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.



* 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 /* */.



* unrestricted code (eg foreign code or unfinished D code commented
out) also cause issues

Superficial

Irrational

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Nick Sabalausky (Abscissa) via Digitalmars-d]

On 02/09/2018 04:23 AM, Kagamin wrote:

On Friday, 9 February 2018 at 08:57:49 UTC, Timothee Cour wrote:

version(none) { FOO } doesn't work if FOO doesn't parse.


version(none)q"EOS
   FOO
EOS";


Huh? So are you *pro-* or *anti-* heredoc?

But ok, that works, unless the code contains `EOS"`. Better change it to:

version(none)q"hey-hey-hey_dudes_I-bet-NOTHINGinMYcode-is-gonna-useTHIS
   FOO
hey-hey-hey_dudes_I-bet-NOTHINGinMYcode-is-gonna-useTHIS";

At least until I go quoting this post in my code. Crap. Guess then I 
could go back to:


version(none)q"EOS
   FOO
EOS";

Or, y'know, just cut out all the noise and just do:

/+
  FOO
+/

and be done with it.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Nick Sabalausky (Abscissa) via Digitalmars-d]

On 02/09/2018 03:52 AM, Kagamin wrote:
On Friday, 9 February 2018 at 08:44:31 UTC, Nick Sabalausky (Abscissa) 
wrote:

On 02/09/2018 03:42 AM, Kagamin wrote:


Nested comments are superficial though,


Not if you've ever commented out a block of code.


Comment this:


'kay:

// string sedArg="s/ +/ /";

Don't see how that's remotely as common as "*/" in a C-style-comments 
codebase or commenting out something at the sub-statement level, like a 
function argument, type modifier or sub-expression, but hey, I guess if 
you have instances of that all over most functions in your codebase, 
then, yea, I guess disabling code with /+ +/ would be pretty nasty.




Comments don't respect even lexical structure of commented code that you 
expect, version(none) does.


Uhh, you do know that IS nesting, right? And that it fails in far more 
cases than /+ +/ does? And is far less widely supported by editors? And 
that it DOES nest? And also that it nests?

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Kagamin via Digitalmars-d]

On Friday, 9 February 2018 at 08:57:49 UTC, Timothee Cour wrote:

version(none) { FOO } doesn't work if FOO doesn't parse.


version(none)q"EOS
  FOO
EOS";

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Kagamin via Digitalmars-d]

On Friday, 9 February 2018 at 08:54:09 UTC, Timothee Cour wrote:

* `/* */` should never be used

Not a single reason for that


* properly nested `/+ +/` indeed don't cause issues
Disproved two times in this thread. Anyway nothing properly done 
causes issues.


* unrestricted code (eg foreign code or unfinished D code 
commented

out) also cause issues

Superficial

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Timothee Cour via Digitalmars-d]

version(none) { FOO } doesn't work if FOO doesn't parse.

Again, what I proposed is the only 100% reliable way to comment out something

On Fri, Feb 9, 2018 at 12:52 AM, Kagamin via Digitalmars-d
 wrote:
> On Friday, 9 February 2018 at 08:44:31 UTC, Nick Sabalausky (Abscissa)
> wrote:
>>
>> On 02/09/2018 03:42 AM, Kagamin wrote:
>>>
>>>
>>> Nested comments are superficial though,
>>
>>
>> Not if you've ever commented out a block of code.
>
>
> Comment this:
> string sedArg="s/ +/ /";
>
> Comments don't respect even lexical structure of commented code that you
> expect, version(none) does.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Kagamin via Digitalmars-d]

On Friday, 9 February 2018 at 08:44:31 UTC, Nick Sabalausky 
(Abscissa) wrote:

On 02/09/2018 03:42 AM, Kagamin wrote:


Nested comments are superficial though,


Not if you've ever commented out a block of code.


Comment this:
string sedArg="s/ +/ /";

Comments don't respect even lexical structure of commented code 
that you expect, version(none) does.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Timothee Cour via Digitalmars-d]

summary:
* `/* */` should never be used
* properly nested `/+ +/` indeed don't cause issues
* urls cause issues and I've ran into this issue multiple times
* unrestricted code (eg foreign code or unfinished D code commented
out) also cause issues
* hreredoc comments fixes these issues when neeeddd



On Fri, Feb 9, 2018 at 12:49 AM, Nick Sabalausky (Abscissa) via
Digitalmars-d  wrote:
> On 02/09/2018 03:37 AM, Kagamin wrote:
>>
>> /**
>> 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
>> */
>
>
>
> /**
> This is a multi-line comment.
> Be sure to check the various files at extras/foo*/package.d
> And also: https://gcc.gnu.org/onlinedocs/libstdc++/faq.html
> */
>
>
> Kaboom. Thank you, good night.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Nick Sabalausky (Abscissa) via Digitalmars-d]

On 02/09/2018 03:37 AM, Kagamin wrote:

/**
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
*/



/**
This is a multi-line comment.
Be sure to check the various files at extras/foo*/package.d
And also: https://gcc.gnu.org/onlinedocs/libstdc++/faq.html
*/


Kaboom. Thank you, good night.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Kagamin via Digitalmars-d]

On Friday, 9 February 2018 at 03:06:56 UTC, Timothee Cour wrote:

/"EOC
This is a multi-line
heredoc comment allowing
/+ documented unittests containing nesting comments +/


Are you sure documented unittests work that way? 
https://run.dlang.io/is/grNpKK

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Kagamin via Digitalmars-d]

On Friday, 9 February 2018 at 07:04:26 UTC, Nick Sabalausky 
(Abscissa) wrote:
(If I were in change of the world, /** and /* both would be 
compiler errors, banned from all commits, and non-nesting block 
comments of all types would be prohibited from all langauges 
upon pain of...well, pain. They are spawn of satan and should 
never exist.)


Nested comments are superficial though, they were a mistake, 
really.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Nick Sabalausky (Abscissa) via Digitalmars-d]

On 02/09/2018 03:42 AM, Kagamin wrote:


Nested comments are superficial though, 


Not if you've ever commented out a block of code.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Kagamin via Digitalmars-d]

/**
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

*/

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Nick Sabalausky (Abscissa) via Digitalmars-d]

On 02/08/2018 10:06 PM, Timothee Cour wrote:


/"EOC
This is a multi-line
heredoc comment allowing
/+ documented unittests containing nesting comments +/


That shouldn't be an issue as long as you're using /++ doc comments and 
not /** ones. If it IS a problem, I'd regard it as a bug.


(If I were in change of the world, /** and /* both would be compiler 
errors, banned from all commits, and non-nesting block comments of all 
types would be prohibited from all langauges upon pain of...well, pain. 
They are spawn of satan and should never exist.)



and weird urls like https://gcc.gnu.org/onlinedocs/libstdc++/faq.html


*That* is a compelling point: Any embedded langauge (such as URL syntax) 
where +/ is valid. That, and maybe any code examples or discussions 
which, for any reason, intentially involve an unmatched end-of-comment.

Re: proposal: heredoc comments to allow `+/` in comments, eg from urls or documented unittests

[Timothee Cour via Digitalmars-d]

NOTE:
the analog of documenting comments (/++ ...+/ and /** */) could be:

/""EOC
multiline comment
EOC"/

(ie allow both `/""` and `/"` before reading in the heredoc token)


On Thu, Feb 8, 2018 at 7:06 PM, Timothee Cour  wrote:
> same exact idea as motivation for delimited strings
> (https://dlang.org/spec/lex.html#delimited_strings)
>
> ```
>
> auto heredoc = q"EOS
> This is a multi-line
> heredoc string
> EOS"
> ;
>
> /"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"/
>
> ```