Include false positives in avoid_futureor_void documentation

dart-lang/sdk#59232

Author: passsy

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2.7.0
+
+- Enable [`use_truncating_division`](https://dart.dev/tools/linter-rules/use_truncating_division.html)
+- Enable [`avoid_futureor_void`](https://dart.dev/tools/linter-rules/avoid_futureor_void.html)
+
 ## 2.6.2
 
 - Disable [`document_ignores`](https://dart.dev/tools/linter-rules/document_ignores.html) due to unnecessary verbosity

lib/casual.yaml

@@ -44,7 +44,6 @@ linter:
     # https://dart.dev/tools/linter-rules/always_declare_return_types
     # - always_put_required_named_parameters_first
 
-
     # Always use package: imports.
     # While both, relative and package imports are fine, package imports are preferred because they allow for easy find
     # and replace
@@ -130,8 +129,25 @@ linter:
     # https://dart.dev/tools/linter-rules/avoid_empty_else
     # - avoid_empty_else
 
-    # Experimental: Avoid using FutureOr<void> as it's redundant
+    # Avoid using FutureOr<void> because the synchronous type void makes no sense since it can't be assigned to a variable
+    #
+    # Definitly never use it as return type of a function.
+    # 
+    # Exception: It is ok to use it as parameter (also constructor parameter) to accept both a synchronous and asynchronous callback for flexability in API design
+    # 
+    # ```
+    # void executeTask(FutureOr<void> Function() task) async { // ok
+    #   await task();
+    # }
+    # 
+    # void main() {
+    #   executeTask(() => print('Sync task')); // sync is allowed
+    #   executeTask(() async => await Future.delayed(Duration(seconds: 1), () => print('Async task'))); // will be awaited
+    # }
+    # ```
     #
+    # See discusson at https://github.com/dart-lang/sdk/issues/59232
+    # 
     # Dart SDK: >= 3.5.0
     #
     # https://dart.dev/tools/linter-rules/avoid_futureor_void

lib/strict.yaml

@@ -132,8 +132,25 @@ linter:
     # https://dart.dev/tools/linter-rules/avoid_empty_else
     - avoid_empty_else
 
-    # Experimental: Avoid using FutureOr<void> as it's redundant
+    # Avoid using FutureOr<void> because the synchronous type void makes no sense since it can't be assigned to a variable
     #
+    # Definitly never use it as return type of a function.
+    # 
+    # Exception: It is ok to use it as parameter (also constructor parameter) to accept both a synchronous and asynchronous callback for flexability in API design
+    # 
+    # ```
+    # void executeTask(FutureOr<void> Function() task) async { // ok
+    #   await task();
+    # }
+    # 
+    # void main() {
+    #   executeTask(() => print('Sync task')); // sync is allowed
+    #   executeTask(() async => await Future.delayed(Duration(seconds: 1), () => print('Async task'))); // will be awaited
+    # }
+    # ```
+    #
+    # See discusson at https://github.com/dart-lang/sdk/issues/59232
+    # 
     # Dart SDK: >= 3.5.0
     #
     # https://dart.dev/tools/linter-rules/avoid_futureor_void