[dart-misc] 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, at some point; 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' via Dart Misc]

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

Effective Dart <https://www.dartlang.org/effective-dart/documentation/> 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. 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:
///
/.....
/.....
/.....
///

Post by 'Bob Nystrom' via Dart Misc

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

Effective Dart <https://www.dartlang.org/effective-dart/documentation/>
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.
/**
* Some doc comment.
*/
/// Some doc comment.
/** Some doc comment. */
But then your editing experience is worse when a comment becomes longer
/** 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.
/**
* *Something emphatic!*
*
* * A bullet list.
* * Another bullet.
*/
Cheers!
– bob

['Bob Nystrom' via Dart Misc]

Post by krupal shah
///
/.....
/.....
/.....
///

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

– bob

[krupal shah]

then
///
//.....
//.....
//.....
///

On Wed, May 18, 2016 at 10:43 PM, 'Bob Nystrom' via Dart Misc <

Post by 'Bob Nystrom' via Dart Misc

Post by krupal shah
///
/.....
/.....
/.....
///

A line starting with a single slash isn't a comment, so that would be a
parse error.
– bob
--
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

--
Krupal Shah

[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

Post by krupal shah
then
///
//.....
//.....
//.....
///
On Wed, May 18, 2016 at 10:43 PM, 'Bob Nystrom' via Dart Misc <

Post by 'Bob Nystrom' via Dart Misc

Post by krupal shah
///
/.....
/.....
/.....
///

A line starting with a single slash isn't a comment, so that would be a
parse error.
– bob
--
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

--
Krupal Shah

[krupal shah]

then
///
//.....
//.....
//.....
///
good maybe

On Wed, May 18, 2016 at 10:43 PM, 'Bob Nystrom' via Dart Misc <

Post by 'Bob Nystrom' via Dart Misc

Post by krupal shah
///
/.....
/.....
/.....
///

A line starting with a single slash isn't a comment, so that would be a
parse error.
– bob
--
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

--
Krupal Shah

[Filipe Morgado]

It was weird for me as well, at first.

Now that I'm into it, +1 for ///

It's a lot easier to edit and all the lines are equally indented.
It's even easier to read now.