Lint for using /// instead of /** for doc comments

[seaneagan]

https://www.dartlang.org/articles/style-guide/#do-use-doc-comments-when-commenting-members-and-types

This rule is actually specified as detail text within the above linked rule, where it says "Although Dart supports two syntaxes of doc comments (/// and /**), we prefer using /// for doc comments.

So it might worth updating the style guide to have a separate rule which says "PREFER to use /// for doc comments." (Actually, I'd want it to be DO, but not sure how many /** supporters are out there).

There is lots of old code that still uses /**, and it's quite tedious to convert them to ///, so a quick fix for this will be quite handy!

[pq]

+1 for making this a DO. Adding @munificent and @kwalrath for their 2 cents.

[munificent]

In my heart, this is a DO rule but, I think people will get out their torches and pitchforks if we did that. For some reason, a subset of Dart users really really like to pretend they're still writing Java. I don't understand that kind of crazy, but I do fear it.

[pq]

Thanks Bob. To my ears, that's just all the more reason to give users a means to escalate or deescalate individual lints (as per #57153).

[bwilkerson]

We didn't change the comment style when we translated the 'analyzer' package. If there isn't a way to disable this rule we'll probably have to disable lints altogether in order to avoid being deluged with output.

[seaneagan]

Once there automatic fixes for lints are supported, it would be nice to be able to run simple fixes like this one in batch mode over an entire code base (such as analyzer).

[pq]

@bwilkerson : absolutely, yes. In your case, complete deescalation would be the option (though I'd lobby you guys to reconsider). To that end, @seaneagan is spot on, once we have fixes plumbed in, if you changed your mind, we could do a bulk fix-up easily.

[danrubel]

Or just auto-convert all our /** */ comments to /// comments :-)

On Thu, Feb 26, 2015 at 5:24 PM, Brian Wilkerson [email protected]
wrote:

We didn't change the comment style when we translated the 'analyzer'
package. If there isn't a way to disable this rule we'll probably have to
disable lints altogether in order to avoid being deluged with output.

—
Reply to this email directly or view it on GitHub
#57186.

[munificent]

Or just auto-convert all our /** */ comments to /// comments :-)

👍 👍 👍