----- Original Message -----

> From:Jonathan M Davis <jmdavisProg at gmx.com>
> 
> On 2011-03-31 10:14, Steve Schveighoffer wrote:
> > >________________________________
> > >From: Jonathan M Davis <jmdavisProg at gmx.com>
> > >If you use the /++ +/ commenting style, no *'s are necessary and
> the issue
> > >is completely avoided, because the /++ and +/ are the only markers that the comment needs, and the editors don't go and add extra +'s
> or *'s.
> > >Personally, I don't understand why you'd _want_ to have all of
> those
> > >extra *'s.
> > 
> > The * aren't necessary in the /** */ comment style either.? All it does
> is
> > make the whole block stand out as a comment vs. the open and close tag.
> > 
> > /+ and +/ would have the same issue of low visibility.
> 
> Well, many editors shove in the extra *'s on every line, but they won't do that with /++ +/.

in vim, I had to turn on the feature of having the *'s inserted, it wasn't there by default.? Yes many editors do that by default, but an editor is usually configurable in that respect.? The only reason /+ doesn't insert + by default is because it's not a commonly known comment style.

> And I don't understand problems with visibility and ddoc comments, since a ddoc comments shouldn't usually be long enough that it doesn't fit on the screen (though obviously some won't be - such as in-depth module ddoc comments), and other than examples, it's pretty clear that it's _not_ code. The only exception that I can really think of is when you have a long example, and even then, the extra -'s make it clear that it's an example. Are you afraid of not being able to distinguish between a regular comment and a ddoc comment? Since ddoc comments only go above declarations, I wouldn't have thought that that would be a problem.

The problem I have is *seeing* the comments as comments.? The /* or /+ tags do not stick out as much when they are inline with the comments themselves.? It's just the way the human brain works -- it's good and distinguishing things that are separated, but if things are close together and do not have distinct lines, they look like the same thing.? Icouldalsowriteeverythingwithoutspaces,andyoucouldreadit,butit'sjusthardertoread.

> So, if you're complaining about the low visibility of /++ +/, I don't understand that. And isn't the whole point of having /++ +/ in the language was for ddoc comments, with /** */ being accepted because it's use in Java?

The whole point of /+ +/ was to provide nested comments.? In C:

/* opens a comment
/* does not do anything
*/ closes the comment
*/ is a syntax error

But /+ allows nesting:

/+ opens a comment
/+ nests a comment inside the outer comment
+/ closes the inner comment
+/ closes the outer comment

The idea was to leave the C behavior for /* to aid in porting C programs and still provide a way to have properly nested comments.

-Steve

On 2011-03-31 11:54, Steve Schveighoffer wrote:
> ----- Original Message -----
> 
> > From:Jonathan M Davis <jmdavisProg at gmx.com>
> > 
> > On 2011-03-31 10:14, Steve Schveighoffer wrote:
> > > >________________________________
> > > >From: Jonathan M Davis <jmdavisProg at gmx.com>
> > > >If you use the /++ +/ commenting style, no *'s are necessary and
> > 
> > the issue
> > 
> > > >is completely avoided, because the /++ and +/ are the only markers that the comment needs, and the editors don't go and add extra +'s
> > 
> > or *'s.
> > 
> > > >Personally, I don't understand why you'd _want_ to have all of
> > 
> > those
> > 
> > > >extra *'s.
> > > 
> > > The * aren't necessary in the /** */ comment style either.  All it does
> > 
> > is
> > 
> > > make the whole block stand out as a comment vs. the open and close tag.
> > > 
> > > /+ and +/ would have the same issue of low visibility.
> > 
> > Well, many editors shove in the extra *'s on every line, but they won't
> > do
> > that with /++ +/.
> 
> in vim, I had to turn on the feature of having the *'s inserted, it wasn't there by default.  Yes many editors do that by default, but an editor is usually configurable in that respect.  The only reason /+ doesn't insert + by default is because it's not a commonly known comment style.
> 
> > And I don't understand problems with visibility and ddoc
> > comments, since a ddoc comments shouldn't usually be long enough that it
> > doesn't fit on the screen (though obviously some won't be - such as
> > in-depth
> > module ddoc comments), and other than examples, it's pretty clear that
> > it's
> > _not_ code. The only exception that I can really think of is when you
> > have a long example, and even then, the extra -'s make it clear that
> > it's an example.
> > Are you afraid of not being able to distinguish between a regular comment
> > and a ddoc comment? Since ddoc comments only go above declarations, I
> > wouldn't have thought that that would be a problem.
> 
> The problem I have is *seeing* the comments as comments.  The /* or /+ tags do not stick out as much when they are inline with the comments themselves.  It's just the way the human brain works -- it's good and distinguishing things that are separated, but if things are close together and do not have distinct lines, they look like the same thing. Icouldalsowriteeverythingwithoutspaces,andyoucouldreadit,butit'sjustharder toread.
> 
> > So, if you're complaining about the low visibility of /++ +/, I don't understand that. And isn't the whole point of having /++ +/ in the language was for ddoc comments, with /** */ being accepted because it's use in Java?
> 
> The whole point of /+ +/ was to provide nested comments.  In C:
> 
> /* opens a comment
> /* does not do anything
> */ closes the comment
> */ is a syntax error
> 
> But /+ allows nesting:
> 
> /+ opens a comment
> /+ nests a comment inside the outer comment
> +/ closes the inner comment
> +/ closes the outer comment
> 
> The idea was to leave the C behavior for /* to aid in porting C programs and still provide a way to have properly nested comments.

/+ +/ yes. However, I was referring to /++ +/. It was my understanding that /++ +/ was created with the idea of it being the way to do ddoc and that /** */ was added, because that's what Java uses. But I could have misunderstood.

I take it that you don't have syntax highlighting on at all then? Since pretty much _any_ code editor is going to mark comments in a different color unless you tell it not to, and since you're apparently using /** */, you're not going to run into problems with it not being supported due to it being D-only.

- Jonathan M Davis