>________________________________
>From: Jonathan M Davis <jmdavisProg at gmx.com>
>
>On 2011-03-31 08:00, Steve Schveighoffer wrote:
>> >________________________________
>> >From: David Simcha <dsimcha at gmail.com>
>> >On Thu, Mar 31, 2011 at 9:29 AM, Steve Schveighoffer <schveiguy at yahoo.com>
>> >wrote:
>> >
>> >One thing I've noticed about std.container, and it makes it very hard for me to read:? Putting all ddoc comments with no indentation.? In particular, I have a very hard time seeing where a class or struct ends. Andrei, there must be a good reason for you to do this, can you explain that?? I'd really prefer that the comments are put at the same indentation as the code being commented.
>> >
>> >>Also, can we standardize the comment style, at least for ddoc comments? I've seen a few different styles in phobos.? My favorite is:
>> >>
>> >>
>> >>/**
>> >> * comment
>> >> */
>> >>
>> >>
>> >>or
>> >>
>> >>/++
>> >> + comment
>> >> +/
>> >>
>> >>
>> >>
>> >>I do not like this:
>> >>
>> >>
>> >>/**
>> >>comment
>> >>*/
>> >
>> >I've switched the other way recently.? The problem with your example is that it's a huge pain when you go to modify the comment and need to keep all those extra *'s in sync.? Furthermore, if you're using an editor with syntax highlighting, I don't find distinguishing comments and code to be even the slightest bit of a problem.
>> 
>> Keeping the *'s in sync has become second nature to me.? Plus my editor makes this easy.? In vim, I use 'J' to join a line to the next one, then 'dw' to delete the *.? Finally, I have 'K' mapped to 'gql', which in one keystroke, inserts all necessary line breaks for the paragraph (for 80 chars) and automatically indents and inserts '*' prefixes.
>
>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.


-Steve

On 2011-03-31 10:14, Steve Schveighoffer wrote:
> >________________________________
> >From: Jonathan M Davis <jmdavisProg at gmx.com>
> >
> >On 2011-03-31 08:00, Steve Schveighoffer wrote:
> >> >________________________________
> >> >From: David Simcha <dsimcha at gmail.com>
> >> >On Thu, Mar 31, 2011 at 9:29 AM, Steve Schveighoffer
> >> ><schveiguy at yahoo.com> wrote:
> >> >
> >> >One thing I've noticed about std.container, and it makes it very hard for me to read:  Putting all ddoc comments with no indentation.  In particular, I have a very hard time seeing where a class or struct ends. Andrei, there must be a good reason for you to do this, can you explain that?  I'd really prefer that the comments are put at the same indentation as the code being commented.
> >> >
> >> >>Also, can we standardize the comment style, at least for ddoc comments? I've seen a few different styles in phobos.  My favorite is:
> >> >>
> >> >>
> >> >>/**
> >> >>
> >> >> * comment
> >> >> */
> >> >>
> >> >>or
> >> >>
> >> >>/++
> >> >>
> >> >> + comment
> >> >> +/
> >> >>
> >> >>I do not like this:
> >> >>
> >> >>
> >> >>/**
> >> >>comment
> >> >>*/
> >> >
> >> >I've switched the other way recently.  The problem with your example is that it's a huge pain when you go to modify the comment and need to keep all those extra *'s in sync.  Furthermore, if you're using an editor with syntax highlighting, I don't find distinguishing comments and code to be even the slightest bit of a problem.
> >> 
> >> Keeping the *'s in sync has become second nature to me.  Plus my editor makes this easy.  In vim, I use 'J' to join a line to the next one, then 'dw' to delete the *.  Finally, I have 'K' mapped to 'gql', which in one keystroke, inserts all necessary line breaks for the paragraph (for 80 chars) and automatically indents and inserts '*' prefixes.
> >
> >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 /++ +/. 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.

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?

- Jonathan M Davis