skip main in avoid_void_async (#3229)

* skip `main` in `avoid_void_async`

* rename

* wordsmithing

* fmt

lib/src/rules/avoid_void_async.dart

@@ -12,10 +12,10 @@ const _desc = r'Avoid async functions that return void.';
 
 const _details = r'''
 
-**DO** mark async functions to return Future<void>.
+**DO** mark async functions as returning Future<void>.
 
 When declaring an async method or function which does not return a value,
-declare that it returns Future<void> and not just void.
+declare that it returns `Future<void>` and not just `void`.
 
 **BAD:**
 ```dart
@@ -29,6 +29,19 @@ Future<void> f() async {}
 Future<void> f2() async => null;
 ```
 
+**EXCEPTION**
+
+An exception is made for top-level `main` functions, where the `Future`
+annotation *can* (and generally should) be dropped in favor of `void`.
+
+**GOOD:**
+```dart
+Future<void> f() async {}
+
+void main() async {
+  await f();
+}
+```
 ''';
 
 class AvoidVoidAsync extends LintRule {
@@ -55,7 +68,9 @@ class _Visitor extends SimpleAstVisitor<void> {
 
   @override
   void visitFunctionDeclaration(FunctionDeclaration node) {
-    if (_isAsync(node.declaredElement) && _isVoid(node.returnType)) {
+    if (_isAsync(node.declaredElement) &&
+        _isVoid(node.returnType) &&
+        node.name.name != 'main') {
       rule.reportLint(node.name);
     }
   }

test/rules/all.dart

@@ -19,6 +19,7 @@ import 'avoid_types_as_parameter_names_test.dart'
     as avoid_types_as_parameter_names;
 import 'avoid_unused_constructor_parameters_test.dart'
     as avoid_unused_constructor_parameters;
+import 'avoid_void_async_test.dart' as avoid_void_async;
 import 'conditional_uri_does_not_exist_test.dart'
     as conditional_uri_does_not_exist;
 import 'deprecated_consistency_test.dart' as deprecated_consistency;
@@ -71,6 +72,7 @@ void main() {
   avoid_shadowing_type_parameters.main();
   avoid_types_as_parameter_names.main();
   avoid_unused_constructor_parameters.main();
+  avoid_void_async.main();
   conditional_uri_does_not_exist.main();
   deprecated_consistency.main();
   file_names.main();

test/rules/avoid_void_async_test.dart

@@ -0,0 +1,28 @@
+// Copyright (c) 2022, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:test_reflective_loader/test_reflective_loader.dart';
+
+import '../rule_test_support.dart';
+
+main() {
+  defineReflectiveSuite(() {
+    defineReflectiveTests(AvoidVoidAsyncTest);
+  });
+}
+
+@reflectiveTest
+class AvoidVoidAsyncTest extends LintRuleTest {
+  @override
+  String get lintRule => 'avoid_void_async ';
+
+  test_main() async {
+    await assertNoDiagnostics(r'''
+Future<void> f() async { }
+void main() async { 
+  await f();
+}
+''');
+  }
+}