Dartdoc comment style

[Mark Haase]

The Dart Style Guide says:

Although Dart supports two syntaxes of doc comments (/// and /**), we prefer using /// for doc comments.

In a separate article, Guidelines for Doc Comments, the examples show /// comments but this convention is not explicitly stated. Confusingly, this article says:

For an example of a class description with example code, see Completer (generated doc, source code).

The link leads to the source code for Completer, which only uses /** comments, not ///. In fact, glancing through various parts of the Dart library, I can't find *any* source code that uses /// comments.

Is this a convention that has changed recently? The reason I ask is that my text editor does not handle '///' comments correctly, and before I file a bug report I want to make sure that I understand that /// comments are actually a real convention.

Also, what is the justification for the /// convention? I find /** to be more readable and more consistent with the conventions of other languages. Besides the 'preference' stated in the Dart style guide, is there any technical reason to prefer /// to /**?

[Bob Nystrom]

On Thu, Mar 12, 2015 at 1:01 PM, Mark Haase <meh...@gmail.com> wrote:

The Dart Style Guide says:

Although Dart supports two syntaxes of doc comments (/// and /**), we prefer using /// for doc comments.

In a separate article, Guidelines for Doc Comments, the examples show /// comments but this convention is not explicitly stated. Confusingly, this article says:

For an example of a class description with example code, see Completer (generated doc, source code).

The link leads to the source code for Completer, which only uses /** comments, not ///. In fact, glancing through various parts of the Dart library, I can't find *any* source code that uses /// comments.

Many of the packages we maintain do. The core libraries less so.

Is this a convention that has changed recently?

If by "recently" you mean "before the core libraries were created", then yes. But most of those were created years ago. :)

This convention changed a year or two ago. I would love to move the core libraries over but I don't own them so I haven't pushed to have that happen. I really hope they do at some point, though.

 

The reason I ask is that my text editor does not handle '///' comments correctly, and before I file a bug report I want to make sure that I understand that /// comments are actually a real convention.

Yes, they are.

 

Also, what is the justification for the /// convention? I find /** to be more readable and more consistent with the conventions of other languages.

Depends on what "other languages" you have in mind. :) C# uses "///" exclusively, but, yes, Javadoc is /**.

 

Besides the 'preference' stated in the Dart style guide, is there any technical reason to prefer /// to /**?

Let's say you start writing a doc comment like:

/** This is a doc comment that is starting to get pretty long and near the end

Oops, you hit 80 columns. To finish the sentence, you need to go back to the beginning of the line and fix it:

/**

 * This is a doc comment that is starting to get pretty long and near the end

Now you can return to the end and pick up where you left off.

/**

 * This is a doc comment that is starting to get pretty long and near the end

 * of the line.

 */

Note that now this comment takes up four lines even though there's only two lines of actual useful documentation.

Now try the other style. You start writing:

/// This is a doc comment that is starting to get pretty long and near the end

And then just move right along to the next line:

/// This is a doc comment that is starting to get pretty long and near the end

/// of the line.

...and you're done. Short and sweet.

I also find /// a little easier on the eyes and, in particular easier to read with comments that contain markdown lists:

/// Groceries:

/// 

/// * Gruyère

/// * Ham

/// * Sourdough

/// * Eggs

versus:

/**

 * Groceries:

 * 

 * * Gruyère

 * * Ham

 * * Sourdough

 * * Eggs

 */

Cheers!

- bob

[Rob Bishop]

I've gravitated to using all '///'s and '//'s for similar readability reasons but also want to point out one nice functional side effect win.  If you stick to commenting this way and then need to comment out a large section of code you can do that with /* */ and not run in to any interference from method comments.

[Bob Nystrom]

On Thu, Mar 12, 2015 at 2:46 PM, Rob Bishop <robbi...@gmail.com> wrote:

If you stick to commenting this way and then need to comment out a large section of code you can do that with /* */ and not run in to any interference from method comments.

This is actually true of either style since Dart allows /* */ to nest, unlike C et. al. :)

Of course, there's a high chance actually using nested block comments will confuse the hell out of your text editor of choice.

- bob

[Mark Haase]

Bob, thanks for the detailed reply. I'd rather swim with the current than against it, so I sent a patch to fix the issue in my text editor and I'm going to stick with /// comments in my Dart project.

May I suggest updating the "Guidelines for Doc Comments" with 2 changes:

1. Explicitly state that /// and /** are supported, but /// is the convention. Given that this convention is probably the first thing a novice needs to learn about dartdoc, I think it makes sense to state the convention at the top of the "Guidlines for Doc Comments" article. (This duplicates the style guide a bit, but the style guide is much broader and readers interested specifically in dartdoc may not read the entire style guide.)
2. Instead of linking to Completer as an example of good dartdoc, link to a class that uses the /// dartdoc style.

I would submit a PR myself but I'm not sure what Dart class to point at as a good example of /// dartdocs. If you can suggest a class with good dartdocs, I'd be happy to submit a PR.

[Bob Nystrom]

On Fri, Mar 13, 2015 at 10:41 AM, Mark Haase <meh...@gmail.com> wrote:

May I suggest updating the "Guidelines for Doc Comments" with 2 changes:

1. Explicitly state that /// and /** are supported, but /// is the convention. Given that this convention is probably the first thing a novice needs to learn about dartdoc, I think it makes sense to state the convention at the top of the "Guidlines for Doc Comments" article. (This duplicates the style guide a bit, but the style guide is much broader and readers interested specifically in dartdoc may not read the entire style guide.)
2. Instead of linking to Completer as an example of good dartdoc, link to a class that uses the /// dartdoc style.

I would submit a PR myself but I'm not sure what Dart class to point at as a good example of /// dartdocs. If you can suggest a class with good dartdocs, I'd be happy to submit a PR.

Great idea. Filed a bug: https://github.com/dart-lang/www.dartlang.org/issues/1280

Thanks!

- bob

[George Moschovitis]

What about adding an command line option to dartfmt in dart_style to automatically convert /** .. */ doc-comments
to /// .. doc-comments?

That would be easy to implement and quite useful.

-g.

[Lasse R.H. Nielsen]

On Sat, Mar 14, 2015 at 3:29 PM, George Moschovitis <george.mo...@gmail.com> wrote:

What about adding an command line option to dartfmt in dart_style to automatically convert /** .. */ doc-comments
to /// .. doc-comments?

That would be easy to implement and quite useful.

It might need reflowing the comments, though, since "/// " is one character more than " * ".

Reflowing isn't easy :)

/L

 -- 

Lasse R.H. Nielsen - l...@google.com  

'Faith without judgement merely degrades the spirit divine'
Google Denmark ApS - Frederiksborggade 20B, 1 sal - 1360 København K - Denmark - CVR nr. 28 86 69 84

[Sean Eagan]

On Sat, Mar 14, 2015 at 9:29 AM George Moschovitis <george.mo...@gmail.com> wrote:

What about adding an command line option to dartfmt in dart_style to automatically convert /** .. */ doc-comments
to /// .. doc-comments?

That would be easy to implement and quite useful.

https://github.com/dart-lang/linter/issues/38

 

-g.



On Friday, March 13, 2015 at 8:07:09 PM UTC+2, Bob wrote:

On Fri, Mar 13, 2015 at 10:41 AM, Mark Haase <meh...@gmail.com> wrote:

May I suggest updating the "Guidelines for Doc Comments" with 2 changes:

1. Explicitly state that /// and /** are supported, but /// is the convention. Given that this convention is probably the first thing a novice needs to learn about dartdoc, I think it makes sense to state the convention at the top of the "Guidlines for Doc Comments" article. (This duplicates the style guide a bit, but the style guide is much broader and readers interested specifically in dartdoc may not read the entire style guide.)
2. Instead of linking to Completer as an example of good dartdoc, link to a class that uses the /// dartdoc style.

I would submit a PR myself but I'm not sure what Dart class to point at as a good example of /// dartdocs. If you can suggest a class with good dartdocs, I'd be happy to submit a PR.

Great idea. Filed a bug: https://github.com/dart-lang/www.dartlang.org/issues/1280

Thanks!

- 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

To unsubscribe from this group and stop receiving emails from it, send an email to misc+uns...@dartlang.org.

[Alex Tatumizer]

Old comment style vs new one: