Add doc checker (#4071)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Documentation**
- Improved and clarified documentation comments for several provider
classes and methods.
- Added and updated documentation templates for better consistency and
clarity.
- **Chores**
- Enhanced the GitHub Actions workflow to include a step for checking
Dart documentation generation.
- Added a script to conditionally run a dry run of Dart documentation
generation based on project configuration.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

examples/stackoverflow/foo.sh

@@ -0,0 +1,3 @@
+if ! grep -q publish_to "pubspec.yaml"; then
+  dart doc --dry-run
+fi

packages/flutter_riverpod/lib/src/core/widget_ref.dart

@@ -16,7 +16,7 @@ part of '../core.dart';
 ///
 /// Once we have a [WidgetRef], we can use its various methods to interact with
 /// providers.
-/// The most common use-case is to use [watch] inside the `build` method of our
+/// The most common use-case is to use [WidgetRef.watch] inside the `build` method of our
 /// widgets. This will enable our UI to update whenever the state of a provider
 /// changes:
 ///

packages/flutter_riverpod/lib/src/providers/legacy/change_notifier_provider.dart

@@ -20,6 +20,7 @@ ProviderElementProxy<NotifierT, NotifierT>
   );
 }
 
+/// {@template riverpod.change_notifier_provider}
 /// Creates a [ChangeNotifier] and exposes its current state.
 ///
 /// Combined with [ChangeNotifier], [ChangeNotifierProvider] can be used to manipulate
@@ -78,6 +79,7 @@ ProviderElementProxy<NotifierT, NotifierT>
 ///   );
 /// }
 /// ```
+/// {@endtemplate}
 final class ChangeNotifierProvider<NotifierT extends ChangeNotifier?>
     extends $FunctionalProvider<NotifierT, NotifierT>
     with LegacyProviderMixin<NotifierT> {

packages/riverpod/lib/src/core/ref.dart

@@ -562,7 +562,7 @@ final <yourProvider> = Provider(dependencies: [<dependency>]);
   /// Listen to a provider and call [listener] whenever its value changes.
   ///
   /// Listeners will automatically be removed when the provider rebuilds (such
-  /// as when a provider listened with [watch] changes).
+  /// as when a provider listened with [Ref.watch] changes).
   ///
   /// Returns an object that allows cancelling the subscription early.
   ///

packages/riverpod/lib/src/mutation.dart

@@ -181,7 +181,7 @@ const mutationZoneKey = #_mutation;
 ///
 /// You can check for the [ErrorMutationState] and [SuccessMutationState] to show a snackbar.
 ///
-/// Since showing snackbars is done using `showSnackBar`, which is not a widget,
+/// Since showing snackbar is done using `showSnackBar`, which is not a widget,
 /// we cannot rely on `ref.watch` here.
 /// Instead, we should use `ref.listen` to listen to the mutation state.
 /// This will give us a callback where we can safely show a snackbar.
@@ -345,7 +345,7 @@ abstract class MutationBase<ResultT> {
   /// If you remove all `watch`/`listen` calls to a mutation, the mutation
   /// will automatically go-back to its [IdleMutationState].
   ///
-  /// If your mutation is always listened, you may want to call [reset] manually
+  /// If your mutation is always listened, you may want to call [MutationBase.reset] manually
   /// to restore the mutation to its [IdleMutationState].
   /// {@endtemplate}
   void reset();

packages/riverpod/lib/src/providers/legacy/state_notifier_provider.dart

@@ -17,6 +17,7 @@ ProviderElementProxy<NotifierT, StateT>
   );
 }
 
+/// {@template riverpod.state_notifier_provider}
 /// Creates a [StateNotifier] and exposes its current state.
 ///
 /// This provider is used in combination with `package:state_notifier`.
@@ -79,13 +80,14 @@ ProviderElementProxy<NotifierT, StateT>
 ///   );
 /// }
 /// ```
+/// {@endtemplate}
 final class StateNotifierProvider< //
         NotifierT extends StateNotifier<StateT>,
         StateT> //
     extends $FunctionalProvider< //
         StateT,
         NotifierT> with LegacyProviderMixin<StateT> {
-  /// {@macro riverpod.statenotifierprovider}
+  /// {@macro riverpod.state_notifier_provider}
   StateNotifierProvider(
     this._create, {
     super.name,

packages/riverpod/lib/src/providers/notifier.dart

@@ -4,6 +4,7 @@ import '../builder.dart';
 import '../common/result.dart';
 import '../framework.dart';
 import 'async_notifier.dart';
+import 'provider.dart';
 
 part 'notifier/orphan.dart';
 part 'notifier/family.dart';

packages/riverpod/lib/src/providers/notifier/orphan.dart

@@ -76,6 +76,11 @@ abstract class Notifier<StateT> extends $Notifier<StateT> {
   }
 }
 
+/// {@template riverpod.notifier_provider}
+/// A provider that exposes a synchronous [Notifier].
+///
+/// [NotifierProvider] can be considered as a mutable [Provider].
+/// {@endtemplate}
 final class NotifierProvider<NotifierT extends Notifier<StateT>, StateT>
     extends $NotifierProvider<NotifierT, StateT>
     with LegacyProviderMixin<StateT> {