Translation [KO]: Comments in code (#3514)

This PR adds "{@template}" to the source code of the documentation, 
and provides the latest Korean translation (include comments in code) of
the �following pages.

- introduction: 2 pages
- essentials: 11 pages
- from_provider: 2 pages
- advanced: 1 page

Thanks

---------

Co-authored-by: Remi Rousselet <[email protected]>

website/docs/advanced/select/select/raw.dart

@@ -17,11 +17,15 @@ final provider = Provider(
 class ConsumerExample extends ConsumerWidget {
   @override
   Widget build(BuildContext context, WidgetRef ref) {
+    // {@template watch}
     // Instead of writing:
     // String name = ref.watch(provider).firstName!;
     // We can write:
+    // {@endtemplate}
     String name = ref.watch(provider.select((it) => it.firstName));
+    // {@template note}
     // This will cause the widget to only listen to changes on "firstName".
+    // {@endtemplate}
 
     return Text('Hello $name');
   }

website/docs/case_studies/cancel/detail_screen_cancel/codegen.dart

@@ -10,18 +10,26 @@ part 'codegen.g.dart';
 /* SNIPPET START */
 @riverpod
 Future<Activity> activity(ActivityRef ref) async {
+  // {@template client}
   // We create an HTTP client using package:http
+  // {@endtemplate}
   final client = http.Client();
+  // {@template onDispose}
   // On dispose, we close the client.
   // This will cancel any pending request that the client might have.
+  // {@endtemplate}
   ref.onDispose(client.close);
 
-  // We now use the client to make the request instead of the "get" function
+  // {@template get}
+  // We now use the client to make the request instead of the "get" function.
+  // {@endtemplate}
   final response = await client.get(
     Uri.https('www.boredapi.com', '/api/activity'),
   );
 
+  // {@template jsonDecode}
   // The rest of the code is the same as before
+  // {@endtemplate}
   final json = jsonDecode(response.body) as Map;
   return Activity.fromJson(Map.from(json));
 }

website/docs/case_studies/cancel/detail_screen_cancel/raw.dart

@@ -7,18 +7,26 @@ import '../detail_screen/codegen.dart';
 
 /* SNIPPET START */
 final activityProvider = FutureProvider.autoDispose<Activity>((ref) async {
+  // {@template client}
   // We create an HTTP client using package:http
+  // {@endtemplate}
   final client = http.Client();
+  // {@template onDispose}
   // On dispose, we close the client.
   // This will cancel any pending request that the client might have.
+  // {@endtemplate}
   ref.onDispose(client.close);
 
+  // {@template get}
   // We now use the client to make the request instead of the "get" function.
+  // {@endtemplate}
   final response = await client.get(
     Uri.https('www.boredapi.com', '/api/activity'),
   );
 
+  // {@template jsonDecode}
   // The rest of the code is the same as before
+  // {@endtemplate}
   final json = jsonDecode(response.body) as Map;
   return Activity.fromJson(Map.from(json));
 });

website/docs/case_studies/cancel/detail_screen_debounce/codegen.dart

@@ -10,21 +10,29 @@ part 'codegen.g.dart';
 /* SNIPPET START */
 @riverpod
 Future<Activity> activity(ActivityRef ref) async {
+  // {@template didDispose}
   // We capture whether the provider is currently disposed or not.
+  // {@endtemplate}
   var didDispose = false;
   ref.onDispose(() => didDispose = true);
 
+  // {@template delayed}
   // We delay the request by 500ms, to wait for the user to stop refreshing.
+  // {@endtemplate}
   await Future<void>.delayed(const Duration(milliseconds: 500));
 
+  // {@template cancelled}
   // If the provider was disposed during the delay, it means that the user
   // refreshed again. We throw an exception to cancel the request.
   // It is safe to use an exception here, as it will be caught by Riverpod.
+  // {@endtemplate}
   if (didDispose) {
     throw Exception('Cancelled');
   }
 
+  // {@template http}
   // The following code is unchanged from the previous snippet
+  // {@endtemplate}
   final client = http.Client();
   ref.onDispose(client.close);
 

website/docs/case_studies/cancel/detail_screen_debounce/raw.dart

@@ -7,21 +7,29 @@ import '../detail_screen/codegen.dart';
 
 /* SNIPPET START */
 final activityProvider = FutureProvider.autoDispose<Activity>((ref) async {
+  // {@template didDispose}
   // We capture whether the provider is currently disposed or not.
+  // {@endtemplate}
   var didDispose = false;
   ref.onDispose(() => didDispose = true);
 
+  // {@template delayed}
   // We delay the request by 500ms, to wait for the user to stop refreshing.
+  // {@endtemplate}
   await Future<void>.delayed(const Duration(milliseconds: 500));
 
+  // {@template cancelled}
   // If the provider was disposed during the delay, it means that the user
   // refreshed again. We throw an exception to cancel the request.
   // It is safe to use an exception here, as it will be caught by Riverpod.
+  // {@endtemplate}
   if (didDispose) {
     throw Exception('Cancelled');
   }
 
+  // {@template http}
   // The following code is unchanged from the previous snippet
+  // {@endtemplate}
   final client = http.Client();
   ref.onDispose(client.close);
 

website/docs/case_studies/cancel/extension.dart

@@ -3,30 +3,42 @@ import 'package:http/http.dart' as http;
 
 /* SNIPPET START */
 extension DebounceAndCancelExtension on Ref {
+  // {@template note}
   /// Wait for [duration] (defaults to 500ms), and then return a [http.Client]
   /// which can be used to make a request.
   ///
   /// That client will automatically be closed when the provider is disposed.
+  // {@endtemplate}
   Future<http.Client> getDebouncedHttpClient([Duration? duration]) async {
+    // {@template didDispose}
     // First, we handle debouncing.
+    // {@endtemplate}
     var didDispose = false;
     onDispose(() => didDispose = true);
 
+    // {@template delay}
     // We delay the request by 500ms, to wait for the user to stop refreshing.
+    // {@endtemplate}
     await Future<void>.delayed(duration ?? const Duration(milliseconds: 500));
 
+    // {@template cancel}
     // If the provider was disposed during the delay, it means that the user
     // refreshed again. We throw an exception to cancel the request.
     // It is safe to use an exception here, as it will be caught by Riverpod.
+    // {@endtemplate}
     if (didDispose) {
       throw Exception('Cancelled');
     }
 
+    // {@template client}
     // We now create the client and close it when the provider is disposed.
+    // {@endtemplate}
     final client = http.Client();
     onDispose(client.close);
 
+    // {@template return}
     // Finally, we return the client to allow our provider to make the request.
+    // {@endtemplate}
     return client;
   }
 }

website/docs/case_studies/cancel/provider_with_extension/codegen.dart

@@ -10,12 +10,16 @@ part 'codegen.g.dart';
 /* SNIPPET START */
 @riverpod
 Future<Activity> activity(ActivityRef ref) async {
+  // {@template client}
   // We obtain an HTTP client using the extension we created earlier.
+  // {@endtemplate}
   final client = await ref.getDebouncedHttpClient();
 
+  // {@template get}
   // We now use the client to make the request instead of the "get" function.
   // Our request will naturally be debounced and be cancelled if the user
   // leaves the page.
+  // {@endtemplate}
   final response = await client.get(
     Uri.https('www.boredapi.com', '/api/activity'),
   );

website/docs/case_studies/cancel/provider_with_extension/raw.dart

@@ -7,12 +7,16 @@ import '../extension.dart';
 
 /* SNIPPET START */
 final activityProvider = FutureProvider.autoDispose<Activity>((ref) async {
+  // {@template client}
   // We obtain an HTTP client using the extension we created earlier.
+  // {@endtemplate}
   final client = await ref.getDebouncedHttpClient();
 
+  // {@template get}
   // We now use the client to make the request instead of the "get" function.
   // Our request will naturally be debounced and be cancelled if the user
   // leaves the page.
+  // {@endtemplate}
   final response = await client.get(
     Uri.https('www.boredapi.com', '/api/activity'),
   );

website/docs/case_studies/pull_to_refresh/display_activity.dart

@@ -14,7 +14,9 @@ class ActivityView extends ConsumerWidget {
     return Scaffold(
       appBar: AppBar(title: const Text('Pull to refresh')),
       body: Center(
+        // {@template render}
         // If we have an activity, display it, otherwise wait
+        // {@endtemplate}
         child: Text(activity.valueOrNull?.activity ?? ''),
       ),
     );

website/docs/case_studies/pull_to_refresh/display_activity3.dart

@@ -14,9 +14,11 @@ class ActivityView extends ConsumerWidget {
     return Scaffold(
       appBar: AppBar(title: const Text('Pull to refresh')),
       body: RefreshIndicator(
+        // {@template onRefresh}
         // By refreshing "activityProvider.future", and returning that result,
         // the refresh indicator will keep showing until the new activity is
         // fetched.
+        // {@endtemplate}
         /* highlight-start */
         onRefresh: () => ref.refresh(activityProvider.future),
         /* highlight-end */

website/docs/case_studies/pull_to_refresh/display_activity4.dart

@@ -19,13 +19,18 @@ class ActivityView extends ConsumerWidget {
         child: ListView(
           children: [
             switch (activity) {
+              // {@template data}
               // If some data is available, we display it.
               // Note that data will still be available during a refresh.
-              AsyncValue<Activity>(:final valueOrNull?) =>
-                Text(valueOrNull.activity),
+              // {@endtemplate}
+              AsyncValue<Activity>(:final valueOrNull?) => Text(valueOrNull.activity),
+              // {@template error}
               // An error is available, so we render it.
+              // {@endtemplate}
               AsyncValue(:final error?) => Text('Error: $error'),
+              // {@template loading}
               // No data/error, so we're in loading state.
+              // {@endtemplate}
               _ => const CircularProgressIndicator(),
             },
           ],

website/docs/essentials/auto_dispose/cache_for_extension.dart

@@ -4,15 +4,23 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 
 /* SNIPPET START */
 extension CacheForExtension on AutoDisposeRef<Object?> {
+  // {@template cacheFor}
   /// Keeps the provider alive for [duration].
+  // {@endtemplate}
   void cacheFor(Duration duration) {
+    // {@template keepAlive}
     // Immediately prevent the state from getting destroyed.
+    // {@endtemplate}
     final link = keepAlive();
+    // {@template timer}
     // After duration has elapsed, we re-enable automatic disposal.
+    // {@endtemplate}
     final timer = Timer(duration, link.close);
 
+    // {@template onDispose}
     // Optional: when the provider is recomputed (such as with ref.watch),
     // we cancel the pending timer.
+    // {@endtemplate}
     onDispose(timer.cancel);
   }
 }

website/docs/essentials/auto_dispose/cache_for_usage/codegen.dart

@@ -10,7 +10,9 @@ part 'codegen.g.dart';
 /* SNIPPET START */
 @riverpod
 Future<Object> example(ExampleRef ref) async {
+  // {@template cacheFor}
   /// Keeps the state alive for 5 minutes
+  // {@endtemplate}
   ref.cacheFor(const Duration(minutes: 5));
 
   return http.get(Uri.https('example.com'));

website/docs/essentials/auto_dispose/cache_for_usage/raw.dart

@@ -7,7 +7,9 @@ import '../cache_for_extension.dart';
 
 /* SNIPPET START */
 final provider = FutureProvider.autoDispose<Object>((ref) async {
+  // {@template cacheFor}
   /// Keeps the state alive for 5 minutes
+  // {@endtemplate}
   ref.cacheFor(const Duration(minutes: 5));
 
   return http.get(Uri.https('example.com'));

website/docs/essentials/auto_dispose/codegen_keep_alive.dart

@@ -3,8 +3,10 @@ import 'package:riverpod_annotation/riverpod_annotation.dart';
 part 'codegen_keep_alive.g.dart';
 
 /* SNIPPET START */
+// {@template keepAlive}
 // We can specify "keepAlive" in the annotation to disable
 // the automatic state destruction
+// {@endtemplate}
 @Riverpod(keepAlive: true)
 int example(ExampleRef ref) {
   return 0;

website/docs/essentials/auto_dispose/invalidate_example.dart

@@ -14,7 +14,9 @@ class MyWidget extends ConsumerWidget {
   Widget build(BuildContext context, WidgetRef ref) {
     return ElevatedButton(
       onPressed: () {
+        // {@template invalidate}
         // On click, destroy the provider.
+        // {@endtemplate}
         ref.invalidate(someProvider);
       },
       child: const Text('dispose a provider'),

website/docs/essentials/auto_dispose/invalidate_family_example/codegen.dart

@@ -16,9 +16,13 @@ String label(LabelRef ref, String userName) {
 // ...
 
 void onTap() {
+  // {@template invalidateAll}
   // Invalidate all possible parameter combinations of this provider.
+  // {@endtemplate}
   ref.invalidate(labelProvider);
+  // {@template invalidate}
   // Invalidate a specific combination only
+  // {@endtemplate}
   ref.invalidate(labelProvider('John'));
 }
 /* SNIPPET END */

website/docs/essentials/auto_dispose/invalidate_family_example/raw.dart

@@ -12,9 +12,13 @@ final provider = Provider.autoDispose.family<String, String>((ref, name) {
 // ...
 
 void onTap() {
+  // {@template invalidateAll}
   // Invalidate all possible parameter combinations of this provider.
+  // {@endtemplate}
   ref.invalidate(provider);
+  // {@template invalidate}
   // Invalidate a specific combination only
+  // {@endtemplate}
   ref.invalidate(provider('John'));
 }
 /* SNIPPET END */

website/docs/essentials/auto_dispose/keep_alive/codegen.dart

@@ -9,12 +9,16 @@ part 'codegen.g.dart';
 @riverpod
 Future<String> example(ExampleRef ref) async {
   final response = await http.get(Uri.parse('https://example.com'));
+  // {@template keepAlive}
   // We keep the provider alive only after the request has successfully completed.
-  // If the request failed (and threw), then when the provider stops being
-  // listened, the state will be destroyed.
+  // If the request failed (and threw an exception), then when the provider stops being
+  // listened to, the state will be destroyed.
+  // {@endtemplate}
   ref.keepAlive();
 
+  // {@template closeLink}
   // We can use the `link` to restore the auto-dispose behavior with:
+  // {@endtemplate}
   // link.close();
 
   return response.body;

website/docs/essentials/auto_dispose/keep_alive/raw.dart

@@ -6,12 +6,16 @@ import 'package:riverpod_annotation/riverpod_annotation.dart';
 /* SNIPPET START */
 final provider = FutureProvider.autoDispose<String>((ref) async {
   final response = await http.get(Uri.parse('https://example.com'));
+  // {@template keepAlive}
   // We keep the provider alive only after the request has successfully completed.
   // If the request failed (and threw an exception), then when the provider stops being
   // listened to, the state will be destroyed.
+  // {@endtemplate}
   final link = ref.keepAlive();
 
+  // {@template closeLink}
   // We can use the `link` to restore the auto-dispose behavior with:
+  // {@endtemplate}
   // link.close();
 
   return response.body;

website/docs/essentials/auto_dispose/on_dispose_example/codegen.dart

@@ -14,10 +14,14 @@ int other(OtherRef ref) => 0;
 Stream<int> example(ExampleRef ref) {
   final controller = StreamController<int>();
 
+  // {@template onDispose}
   // When the state is destroyed, we close the StreamController.
+  // {@endtemplate}
   ref.onDispose(controller.close);
 
+  // {@template todo}
   // TO-DO: Push some values in the StreamController
+  // {@endtemplate}
   return controller.stream;
 }
 /* SNIPPET END */