Why three-slash comments are encouraged over slash-star comments in DartDoc?

[krupal shah]

Sorry but I don't know the exact reason or any history about why Dart now encourages three slash syntax (///...///) over slash-star comments (/**...**/) for doc comments.

For some reason, Rust also seems to have this kind of syntax for doc comments.

Imho, three slash syntax looks very much noisy while reading code.

I am curious why did they take this kind of weird syntax for doc comments into dart?

[Bob Nystrom]

On Tue, May 17, 2016 at 12:44 PM, krupal shah <krupal...@gmail.com> wrote:

I am curious why did they take this kind of weird syntax for doc comments into dart?

Effective Dart has some of the motivation:

We prefer /// because it’s more compact. /** and */ add two content-free lines to a multiline doc comment. The /// syntax is also easier to read in some situations, such as when a doc comment contains a bulleted list that uses * to mark list items.

JavaDoc style takes up a lot of space. Consider:

/**

 * Some doc comment.

 */

Versus:

/// Some doc comment.

You can do single-line JavaDoc style:

/** Some doc comment. */

But then your editing experience is worse when a comment becomes longer than a single line. You type:

/** Some doc comment that is about to overflow onto the second line...

And now you have to go back to the beginning to add a line break after the /**, and then return to the end of the line to complete your though. That line break changes the length of the line, so sometimes now it wraps differently. It's a hassle.

Also, JavaDoc style comments look funny if you use * in Markdown:

/**

 * *Something emphatic!*

 *

 * * A bullet list.

 * * Another bullet.

 */

Cheers!

– bob

[David Notik]

Totally agree with the reasoning.

[krupal shah]

Agree for these cases. They are rare cases btw. But when I'm reading dart code without any IDE such as on news.dartlang.org or maybe on stackoverflow; three slash comments are harder to read.

I think that is because three slashes on every line.

Can't it be changed from 

///

///.....

///.....

///

to something more compact like:

///

/.....

/.....

/.....

///

[Bob Nystrom]

On Wed, May 18, 2016 at 8:21 AM, krupal shah <krupal...@gmail.com> wrote:

to something more compact like:

///

/.....

/.....

/.....

///

A line starting with a single slash isn't a comment, so that would be a parse error.

– bob

[krupal shah]

then

///

//.....

//.....

//.....

///

--
For other discussions, see https://groups.google.com/a/dartlang.org/
 
For HOWTO questions, visit http://stackoverflow.com/tags/dart
 
To file a bug report or feature request, go to http://www.dartbug.com/new
---
You received this message because you are subscribed to the Google Groups "Dart Misc" group.
To unsubscribe from this group and stop receiving emails from it, send an email to misc+uns...@dartlang.org.

--

Krupal Shah

[krupal shah]

then

///

//.....

//.....

//.....

///

good maybe

On Wed, May 18, 2016 at 10:43 PM, 'Bob Nystrom' via Dart Misc <mi...@dartlang.org> wrote:

--
For other discussions, see https://groups.google.com/a/dartlang.org/
 
For HOWTO questions, visit http://stackoverflow.com/tags/dart
 
To file a bug report or feature request, go to http://www.dartbug.com/new
---
You received this message because you are subscribed to the Google Groups "Dart Misc" group.
To unsubscribe from this group and stop receiving emails from it, send an email to misc+uns...@dartlang.org.

--

Krupal Shah

[Filipe Morgado]

It was weird for me as well, at first.

Now that I'm into it, I find it easier to read (+ all the reasons Bob said).

I can't see any downside now.

[Matthew Butler]

This would re-invoke first two issues that Bob mentioned that the triple slash solved. That being the extra, unnecessary lines and single line dart doc comments which later need to be expanded to multiple lines. I honestly don't see what problem your suggestion is trying to solve, nor how it solves it? (Not trying to be offensive, I just don't see the motivation behind this proposed change?)

Matt