From 11c8fcde735ebd9e44dee14c900af5a4b77b4e68 Mon Sep 17 00:00:00 2001 From: TimIconica Date: Tue, 20 Sep 2022 11:58:06 +0200 Subject: [PATCH] fix: documentation fixes --- lib/next_shell/form.dart | 6 +-- lib/next_shell/providers.dart | 1 + lib/src/widgets/input/abstractions.dart | 10 ++--- .../input_carousel/carousel_controller.dart | 6 ++- .../input_carousel/carousel_options.dart | 38 +++++++++++-------- .../input_carousel/carousel_slider.dart | 10 ++--- .../input_carousel/carousel_state.dart | 2 +- .../input_password/input_password.dart | 6 +-- .../input_types/input_password/password.dart | 10 +++-- .../input/input_types/input_plain_text.dart | 4 +- .../input_slider/input_slider.dart | 2 +- 11 files changed, 53 insertions(+), 42 deletions(-) diff --git a/lib/next_shell/form.dart b/lib/next_shell/form.dart index 1a20cf5..d1b6855 100644 --- a/lib/next_shell/form.dart +++ b/lib/next_shell/form.dart @@ -5,15 +5,15 @@ import 'package:flutter/material.dart'; /// The pages determine what pages the pageview will contain via a [List] of [ShellFormPage]s. /// /// Using a checkpage gives the ability for the user to check all input values before commiting by [CheckPage]. -/// If [checkpage] is null no check page will be shown. +/// If [checkPage] is null no check page will be shown. /// /// [nextButton] and [backButton] are both a way to give controls to user. /// Both are just plain widgets used in a [Stack]. So the widgets can be aligned where ever. /// The formcontroller of [ShellForm] should be used to give control to the widgets/buttons. /// /// [onFinished] and [onNext] are both callbacks which give the users results. -/// onNext is called when the user goes to the next page. -/// onFinished is called when the form is finished. When checkpage is set onFinished is called when the checkpage is finished. +/// [onNext] is called when the user goes to the next page. +/// [onFinished] is called when the form is finished. When checkpage is set [onFinished] is called when the checkpage is finished. class ShellFormOptions { final List pages; diff --git a/lib/next_shell/providers.dart b/lib/next_shell/providers.dart index cdfb8a1..6a58a6f 100644 --- a/lib/next_shell/providers.dart +++ b/lib/next_shell/providers.dart @@ -1,5 +1,6 @@ import 'package:flutter_form/next_shell/translation_service.dart'; import 'package:flutter_riverpod/flutter_riverpod.dart'; +/// Provides the [ShellTranslationService] final translationServiceProvider = Provider((ref) => ShellTranslationService()); diff --git a/lib/src/widgets/input/abstractions.dart b/lib/src/widgets/input/abstractions.dart index 7d172b7..d49a4cb 100644 --- a/lib/src/widgets/input/abstractions.dart +++ b/lib/src/widgets/input/abstractions.dart @@ -31,13 +31,13 @@ abstract class ShellFormInputWidget extends ConsumerWidget { /// Abstract class for the controller for inputs used in a [ShellForm]. /// -/// The id determines the key in the [Map] returned by the [ShellForm]. +/// The [id] determines the key in the [Map] returned by the [ShellForm]. /// -/// value is a way to set a initial value. +/// [value] is a way to set a initial value. /// -/// mandatory determines if the input is mandatory. +/// [mandatory] determines if the input is mandatory. /// -/// checkPageTitle is a function where you can transform the value from the input into something representable. +/// [checkPageTitle] is a function where you can transform the value from the input into something representable. /// This value will be given when defining the check page widgets. /// If this function is not set, the value will be used as is. /// Example: @@ -47,7 +47,7 @@ abstract class ShellFormInputWidget extends ConsumerWidget { /// }, /// ``` /// -/// checkPageDescription is the same as checkPageTitle but for the description. +/// [checkPageDescription] is the same as checkPageTitle but for the description. /// If null no description will be shown. abstract class ShellFormInputController { String? id; diff --git a/lib/src/widgets/input/input_types/input_carousel/carousel_controller.dart b/lib/src/widgets/input/input_types/input_carousel/carousel_controller.dart index e05b1d1..253b98a 100644 --- a/lib/src/widgets/input/input_types/input_carousel/carousel_controller.dart +++ b/lib/src/widgets/input/input_types/input_carousel/carousel_controller.dart @@ -100,7 +100,8 @@ class CarouselControllerImpl implements CarouselController { return _state!.pageController!.jumpToPage(pageToJump); } - /// Animates the controlled [CarouselSlider] from the current page to the given page. + /// Animates the controlled [CarouselSlider] from the current page to the + /// given page. /// /// The animation lasts for the given duration and follows the given curve. /// The returned [Future] resolves when the animation completes. @@ -136,7 +137,8 @@ class CarouselControllerImpl implements CarouselController { /// Stops the controlled [CarouselSlider] from autoplaying. /// /// This is a more on-demand way of doing this. Use the [autoPlay] - /// parameter in [CarouselOptions] to specify the autoPlay behaviour of the carousel. + /// parameter in [CarouselOptions] to specify the autoPlay behaviour of the + /// carousel. @override void stopAutoPlay() { _state!.onResetTimer(); diff --git a/lib/src/widgets/input/input_types/input_carousel/carousel_options.dart b/lib/src/widgets/input/input_types/input_carousel/carousel_options.dart index 4aad82f..a88b1fa 100644 --- a/lib/src/widgets/input/input_types/input_carousel/carousel_options.dart +++ b/lib/src/widgets/input/input_types/input_carousel/carousel_options.dart @@ -35,17 +35,17 @@ class CarouselOptions { /// Enables auto play, sliding one page at a time. /// - /// Use [autoPlayInterval] to determent the frequency of slides. + /// Use [autoPlayInterval] to determine the frequency of slides. /// Defaults to false. final bool autoPlay; - /// Sets Duration to determent the frequency of slides when - /// - /// [autoPlay] is set to true. + /// Sets Duration to determine the frequency of slides when [autoPlay] is set + /// to true. /// Defaults to 4 seconds. final Duration autoPlayInterval; - /// The animation duration between two transitioning pages while in auto playback. + /// The animation duration between two transitioning pages while in auto + /// playback. /// /// Defaults to 800 ms. final Duration autoPlayAnimationDuration; @@ -88,40 +88,46 @@ class CarouselOptions { /// Default to `true`. final bool pageSnapping; - /// If `true`, the auto play function will be paused when user is interacting with - /// the carousel, and will be resumed when user finish interacting. + /// If `true`, the auto play function will be paused when user is interacting + /// with the carousel, and will be resumed when user finish interacting. + /// /// Default to `true`. final bool pauseAutoPlayOnTouch; /// If `true`, the auto play function will be paused when user is calling - /// pageController's `nextPage` or `previousPage` or `animateToPage` method. + /// [PageController]'s [nextPage] or [previousPage] or [animateToPage] method. /// And after the animation complete, the auto play will be resumed. + /// /// Default to `true`. final bool pauseAutoPlayOnManualNavigate; - /// If `enableInfiniteScroll` is `false`, and `autoPlay` is `true`, this option + /// If [enableInfiniteScroll] is `false`, and [autoPlay] is `true`, this option /// decide the carousel should go to the first item when it reach the last item or not. /// If set to `true`, the auto play will be paused when it reach the last item. - /// If set to `false`, the auto play function will animate to the first item when it was - /// in the last item. + /// If set to `false`, the auto play function will animate to the first item + /// when it was in the last item. final bool pauseAutoPlayInFiniteScroll; - /// Pass a `PageStoragekey` if you want to keep the pageview's position when it was recreated. + /// Pass a [PageStorageKey] if you want to keep the pageview's position when + /// it was recreated. final PageStorageKey? pageViewKey; - /// Use `enlargeStrategy` to determine which method to enlarge the center page. + /// Use [enlargeStrategy] to determine which method to enlarge the center page. final CenterPageEnlargeStrategy enlargeStrategy; - /// Whether or not to disable the `Center` widget for each slide. + /// Whether or not to disable the [Center] widget for each slide. final bool disableCenter; /// Whether to add padding to both ends of the list. - /// If this is set to true and [viewportFraction] < 1.0, padding will be added such that the first and last child slivers will be in the center of the viewport when scrolled all the way to the start or end, respectively. + /// If this is set to true and [viewportFraction] < 1.0, padding will be added + /// such that the first and last child slivers will be in the center of the 1 + /// viewport when scrolled all the way to the start or end, respectively. + /// /// If [viewportFraction] >= 1.0, this property has no effect. /// This property defaults to true and must not be null. final bool padEnds; - /// Exposed clipBehavior of PageView + /// Exposed [clipBehavior] of [PageView] final Clip clipBehavior; CarouselOptions({ diff --git a/lib/src/widgets/input/input_types/input_carousel/carousel_slider.dart b/lib/src/widgets/input/input_types/input_carousel/carousel_slider.dart index 64a8a81..96b43e8 100644 --- a/lib/src/widgets/input/input_types/input_carousel/carousel_slider.dart +++ b/lib/src/widgets/input/input_types/input_carousel/carousel_slider.dart @@ -17,14 +17,14 @@ typedef ExtendedIndexedWidgetBuilder = Widget Function( BuildContext context, int index, int realIndex); class CarouselSlider extends StatefulWidget { - /// [CarouselOptions] to create a [CarouselState] with + /// [CarouselOptions] to create a [CarouselState] with. final CarouselOptions options; - /// The widgets to be shown in the carousel of default constructor + /// The widgets to be shown in the carousel of default constructor. final List? items; /// The widget item builder that will be used to build item on demand - /// The third argument is the PageView's real index, can be used to cooperate + /// The third argument is the [PageView]'s real index, can be used to cooperate /// with Hero. final ExtendedIndexedWidgetBuilder? itemBuilder; @@ -45,7 +45,7 @@ class CarouselSlider extends StatefulWidget { : CarouselController() as CarouselControllerImpl, super(key: key); - /// The on demand item builder constructor + /// The on demand item builder constructor/ CarouselSlider.builder( {required this.itemCount, required this.itemBuilder, @@ -73,7 +73,7 @@ class CarouselSliderState extends State PageController? pageController; - /// mode is related to why the page is being changed + /// [mode] is related to why the page is being changed CarouselPageChangedReason mode = CarouselPageChangedReason.controller; CarouselSliderState(); diff --git a/lib/src/widgets/input/input_types/input_carousel/carousel_state.dart b/lib/src/widgets/input/input_types/input_carousel/carousel_state.dart index 313911d..df2e01c 100644 --- a/lib/src/widgets/input/input_types/input_carousel/carousel_state.dart +++ b/lib/src/widgets/input/input_types/input_carousel/carousel_state.dart @@ -23,7 +23,7 @@ class CarouselState { /// The widgets count that should be shown at carousel int? itemCount; - /// Will be called when using pageController to go to next page or + /// Will be called when using [pageController] to go to next page or /// previous page. It will clear the autoPlay timer. /// Internal use only Function onResetTimer; diff --git a/lib/src/widgets/input/input_types/input_password/input_password.dart b/lib/src/widgets/input/input_types/input_password/input_password.dart index cb58aca..ec7eac6 100644 --- a/lib/src/widgets/input/input_types/input_password/input_password.dart +++ b/lib/src/widgets/input/input_types/input_password/input_password.dart @@ -17,7 +17,7 @@ class ShellFormInputPassword extends ShellFormInputWidget { Widget build(BuildContext context, WidgetRef ref) { super.registerController(context); - return PasswordTextfield( + return PasswordTextField( label: label, controller: controller, ); @@ -62,11 +62,11 @@ class ShellFormInputPasswordController String Function(String, {List? params}) translator) { if (mandatory) { if (value == null || value.isEmpty) { - return translator('shell.form.error.empty'); + return translator('Field cannot be empty'); } if (value.length < 6) { - return translator('shell.form.error.empty'); + return translator('Field cannot be empty'); } } diff --git a/lib/src/widgets/input/input_types/input_password/password.dart b/lib/src/widgets/input/input_types/input_password/password.dart index 78479aa..19d5473 100644 --- a/lib/src/widgets/input/input_types/input_password/password.dart +++ b/lib/src/widgets/input/input_types/input_password/password.dart @@ -3,21 +3,23 @@ import 'package:flutter_riverpod/flutter_riverpod.dart'; import '../../../../../flutter_form.dart'; import 'package:flutter_form/next_shell/translation_service.dart'; -class PasswordTextfield extends ConsumerStatefulWidget { +/// Generates a [TextFormField] for passwords. It requires a [ShellFormInputController] +/// as the [controller] parameter and an optional [Widget] as [label] +class PasswordTextField extends ConsumerStatefulWidget { final Widget? label; final ShellFormInputController controller; - const PasswordTextfield({ + const PasswordTextField({ Key? key, required this.controller, this.label, }) : super(key: key); @override - ConsumerState createState() => _PasswordTextfieldState(); + ConsumerState createState() => _PasswordTextFieldState(); } -class _PasswordTextfieldState extends ConsumerState { +class _PasswordTextFieldState extends ConsumerState { bool obscured = true; @override diff --git a/lib/src/widgets/input/input_types/input_plain_text.dart b/lib/src/widgets/input/input_types/input_plain_text.dart index 3183b5c..a31ca32 100644 --- a/lib/src/widgets/input/input_types/input_plain_text.dart +++ b/lib/src/widgets/input/input_types/input_plain_text.dart @@ -4,7 +4,7 @@ import 'package:flutter_riverpod/flutter_riverpod.dart'; import '../../../../flutter_form.dart'; import 'package:flutter_form/next_shell/translation_service.dart'; -/// Input for an plain text used in a [ShellForm]. +/// Input for plain text input used in a [ShellForm]. /// /// Standard controller is [ShellFormInputPlainTextController]. class ShellFormInputPlainText extends ShellFormInputWidget { @@ -73,7 +73,7 @@ class ShellFormInputPlainTextWhiteWithBorder extends ShellFormInputWidget { } } -/// Controller for plain text used by a [ShellFormInputWidget] used in a [ShellFrom]. +/// Controller for plain text used by a [ShellFormInputWidget] used in a [ShellForm]. /// /// Mainly used by [ShellFormInputPlainText]. class ShellFormInputPlainTextController diff --git a/lib/src/widgets/input/input_types/input_slider/input_slider.dart b/lib/src/widgets/input/input_types/input_slider/input_slider.dart index aabdb52..a795c1b 100644 --- a/lib/src/widgets/input/input_types/input_slider/input_slider.dart +++ b/lib/src/widgets/input/input_types/input_slider/input_slider.dart @@ -35,7 +35,7 @@ class ShellFormInputSlider extends ShellFormInputWidget { } } -/// Controller for slider used by a [ShellFormInputWidget] used in a [ShellFrom]. +/// Controller for slider used by a [ShellFormInputWidget] used in a [ShellForm]. /// /// Mainly used by [ShellFormInputSlider]. class ShellFormInputSliderController