Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Analyzer code base should use '///' doc comments #33892

Closed
stereotype441 opened this issue Jul 17, 2018 · 1 comment
Closed

Analyzer code base should use '///' doc comments #33892

stereotype441 opened this issue Jul 17, 2018 · 1 comment
Labels
analyzer-technical-debt area-analyzer Use area-analyzer for Dart analyzer issues, including the analysis server and code completion. P2 A bug or feature request we're likely to work on type-code-health Internal changes to our tools and workflows to make them cleaner, simpler, or more maintainable

Comments

@stereotype441
Copy link
Member

Effective Dart says:

For historical reasons, dartdoc supports two syntaxes of doc comments: /// (“C# style”) and /** ... */ (“JavaDoc style”). 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.

If you stumble onto code that still uses the JavaDoc style, consider cleaning it up.

The analyzer codebase contains a mixture of the /// and /** ... */ syntaxes. We should clean it up so that it follows the recommendations of Effective Dart.
@stereotype441 stereotype441 added area-analyzer Use area-analyzer for Dart analyzer issues, including the analysis server and code completion. type-code-health Internal changes to our tools and workflows to make them cleaner, simpler, or more maintainable P2 A bug or feature request we're likely to work on labels Jul 17, 2018
@fuzzybinary
Copy link

I took a stab at this and submitted the patch here:
https://dart-review.googlesource.com/c/sdk/+/67241

Not sure if that's correct process?

dart-bot pushed a commit that referenced this issue Jun 26, 2020
@srawlins
Use ///-style doc comments in analyzer/lib/src/dart
a89b7a4 
Bug: #33892
Change-Id: I5c4d112228ab2ee23f59743e005a5fde1ae2fff4
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/152681
Reviewed-by: Paul Berry <paulberry@google.com>
Reviewed-by: Konstantin Shcheglov <scheglov@google.com>
Commit-Queue: Samuel Rawlins <srawlins@google.com>
dart-bot pushed a commit that referenced this issue Jun 26, 2020
@srawlins
Use ///-style doc comments in analyzer/lib/src/generated
baa5717 
Bug: #33892
Change-Id: I0cee47b71702a210c5ace9455ce9aaf914355d05
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/152683
Reviewed-by: Paul Berry <paulberry@google.com>
Reviewed-by: Konstantin Shcheglov <scheglov@google.com>
Commit-Queue: Samuel Rawlins <srawlins@google.com>
dart-bot pushed a commit that referenced this issue Jun 26, 2020
@srawlins
Use ///-style doc comments in analyzer/lib
648b5e9 
Bug: #33892
Change-Id: I573cb81dca6462c571bd6bf7bf309a46fd628967
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/152610
Reviewed-by: Paul Berry <paulberry@google.com>
Reviewed-by: Konstantin Shcheglov <scheglov@google.com>
Commit-Queue: Samuel Rawlins <srawlins@google.com>
dart-bot pushed a commit that referenced this issue Jun 26, 2020
@srawlins
Use ///-style doc comments in analyzer/test
c68fd58 
Bug: #33892
Change-Id: If61e07fda4d74b1e5171d22403b156855cd00596
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/152701
Reviewed-by: Paul Berry <paulberry@google.com>
Reviewed-by: Konstantin Shcheglov <scheglov@google.com>
Commit-Queue: Samuel Rawlins <srawlins@google.com>
dart-bot pushed a commit that referenced this issue Jun 26, 2020
@srawlins
Use ///-style doc comments in analyzer/tool
a558d57 
Bug: #33892
Change-Id: I67094e84af2ec54ede00b248a2e67d3cebadc576
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/152702
Reviewed-by: Paul Berry <paulberry@google.com>
Reviewed-by: Konstantin Shcheglov <scheglov@google.com>
Commit-Queue: Samuel Rawlins <srawlins@google.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
analyzer-technical-debt area-analyzer Use area-analyzer for Dart analyzer issues, including the analysis server and code completion. P2 A bug or feature request we're likely to work on type-code-health Internal changes to our tools and workflows to make them cleaner, simpler, or more maintainable
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@srawlins @fuzzybinary @stereotype441