Updated Paginable to version 1.1.0

Added pub badge to README.md

Updated dependencies

Removed example section from README.md

Added README.md to example folder

Added documentation comments

Author: thechinkysight

README.md

@@ -1,3 +1,5 @@
+[![pub package](https://img.shields.io/pub/v/paginable.svg)](https://pub.dev/packages/paginable)
+
 Paginable is a Flutter package which makes pagination easier.
 
 <p>
@@ -13,7 +15,7 @@ Paginable is a Flutter package which makes pagination easier.
 
 ## Paginable Widgets
 
-- `PaginableListViewBuilder` is paginable's version of [`ListView.builder`](https://api.flutter.dev/flutter/widgets/ListView-class.html)
+- `PaginableListViewBuilder` is paginable's version of [`ListView.builder`](https://api.flutter.dev/flutter/widgets/ListView/ListView.builder.html)
 - `PaginableCustomScrollView` is paginable's version of [`CustomScrollView`](https://api.flutter.dev/flutter/widgets/CustomScrollView-class.html)
 - `PaginableSliverChildBuilderDelegate` is paginable's version of [`SliverChildBuilderDelegate`](https://api.flutter.dev/flutter/widgets/SliverChildBuilderDelegate-class.html)
 
@@ -157,11 +159,6 @@ You might miss that the parameter `loadMore` is in `PaginableCustomScrollView`,
 >
 > Paginable is not resposible for managing states, to know about different ways of managing states in Flutter, [https://flutter.dev/docs/development/data-and-backend/state-mgmt/options](https://flutter.dev/docs/development/data-and-backend/state-mgmt/options)
 
-## Examples
-
-- [Using `PaginableListViewBuilder`](https://github.com/chinkysight/paginable/tree/main/example/paginablelistviewbuilder_example)
-- [Using `PaginableCustomScrollView` with `PaginableSliverChildBuilderDelegate`](https://github.com/chinkysight/paginable/tree/main/example/paginablesliverchildbuilderdelegate_example)
-
 ## Contribution
 
 If you would like to contribute to the package (e.g. by improving the documentation, solving a bug or adding a cool new feature), you are welcomed and very much appreciated to send us your pull request and if you find something wrong with the package, please feel free to open an [issue](https://github.com/chinkysight/paginable/issues).

example/README.md

@@ -0,0 +1,13 @@
+# Examples
+
+## Using `PaginableListViewBuilder`
+
+This example helps to understand the usage of `PaginableListViewBuilder`.
+
+[Jump To Source](https://github.com/chinkysight/paginable/tree/main/example/paginablelistviewbuilder_example)
+
+## Using `PaginableCustomScrollView` with `PaginableSliverChildBuilderDelegate`
+
+This example helps to understand how we can use `PaginableCustomScrollView` with `PaginableSliverChildBuilderDelegate` to perform pagination.
+
+[Jump To Source](https://github.com/chinkysight/paginable/tree/main/example/paginablesliverchildbuilderdelegate_example)

example/paginablelistviewbuilder_example/pubspec.yaml

@@ -11,15 +11,15 @@ environment:
 dependencies:
   flutter:
     sdk: flutter
-  paginable: ^1.0.0
+  paginable: ^1.1.0
 
-  cupertino_icons: ^1.0.2
+  cupertino_icons: ^1.0.3
 
 dev_dependencies:
   flutter_test:
     sdk: flutter
 
-  flutter_lints: ^1.0.0
+  flutter_lints: ^1.0.4
 
 flutter:
   uses-material-design: true

example/paginablesliverchildbuilderdelegate_example/lib/utils.dart

@@ -8,4 +8,4 @@ Future<void> fetchFiveMore() async {
   for (int i = 0; i < 5; i++) {
     numbers.add(numbers.last + 1);
   }
-}
+}

example/paginablesliverchildbuilderdelegate_example/pubspec.yaml

@@ -11,15 +11,15 @@ environment:
 dependencies:
   flutter:
     sdk: flutter
-  paginable: ^1.0.0
+  paginable: ^1.1.0
 
-  cupertino_icons: ^1.0.2
+  cupertino_icons: ^1.0.3
 
 dev_dependencies:
   flutter_test:
     sdk: flutter
 
-  flutter_lints: ^1.0.0
+  flutter_lints: ^1.0.4
 
 flutter:
   uses-material-design: true

example/paginablesliverchildbuilderdelegate_example/test/utils_test.dart

@@ -13,4 +13,4 @@ void main() {
       expect(numbers.length, 25);
     },
   );
-}
+}

lib/src/paginable_custom_scroll_view.dart

@@ -4,7 +4,9 @@ import 'package:provider/provider.dart';
 
 import 'utils/last_item.dart';
 
+/// It is the paginable's version of [CustomScrollView](https://api.flutter.dev/flutter/widgets/CustomScrollView-class.html) and it is used along with [PaginableSliverChildBuilderDelegate](https://pub.dev/packages/paginable#using-paginablecustomscrollview-with-paginablesliverchildbuilderdelegate) to perform pagination.
 class PaginableCustomScrollView extends StatefulWidget {
+  /// It takes an async function which will be executed when the scroll is almost at the end.
   final Future<void> Function() loadMore;
 
   // ignore: annotate_overrides, overridden_fields
@@ -19,13 +21,18 @@ class PaginableCustomScrollView extends StatefulWidget {
   final Key? center;
   final double anchor;
   final double? cacheExtent;
+
+  /// The slivers to place inside the viewport.
   final List<Widget> slivers;
   final int? semanticChildCount;
   final DragStartBehavior dragStartBehavior;
   final ScrollViewKeyboardDismissBehavior keyboardDismissBehavior;
   final String? restorationId;
   final Clip clipBehavior;
 
+  /// Creates a [ScrollView] that creates custom scroll effects using slivers.
+  ///
+  /// See the [ScrollView] constructor for more details on these arguments.
   const PaginableCustomScrollView(
       {this.key,
       this.scrollDirection = Axis.vertical,

lib/src/paginable_listview_builder.dart

@@ -3,12 +3,26 @@ import 'package:flutter/material.dart';
 import 'utils/last_item.dart';
 import 'utils/scroll_position.dart';
 
+/// It is paginable's version of [ListView.builder](https://api.flutter.dev/flutter/widgets/ListView/ListView.builder.html)
 class PaginableListViewBuilder extends StatefulWidget {
   final double? itemExtent;
+
+  /// It takes a function which contains two parameters, one being of type `Exception` and other being a
+  /// `Function()`, returning a widget which will be displayed at the bottom of the scrollview when an
+  /// exception occurs in the async function which we passed to the `loadMore` parameter.
+  ///
+  /// The parameter with type `Exception` will contain the exception which occured while executing the
+  /// function passed to the parameter `loadMore` if exception occured, and the parameter with type `Function()`
+  /// will contain the same function which we passed to the `loadMore` parameter.
   final Widget Function(Exception exception, void Function() tryAgain)
       errorIndicatorWidget;
+
+  /// It takes a widget which will be displayed at the bottom of the scrollview to indicate the user that
+  /// the async function we passed to the `loadMore` parameter is being executed.
   final Widget progressIndicatorWidget;
   final Widget Function(BuildContext context, int index) itemBuilder;
+
+  /// It takes an async function which will be executed when the scroll is almost at the end.
   final Future<void> Function() loadMore;
   final ScrollController? controller;
   final Axis scrollDirection;
@@ -27,6 +41,8 @@ class PaginableListViewBuilder extends StatefulWidget {
   final ScrollViewKeyboardDismissBehavior keyboardDismissBehavior;
   final String? restorationId;
   final Clip clipBehavior;
+
+  /// Creates a scrollable, linear array of widgets that are created on demand.
   const PaginableListViewBuilder(
       {Key? key,
       this.scrollDirection = Axis.vertical,
@@ -112,8 +128,7 @@ class _PaginableListViewBuilderState extends State<PaginableListViewBuilder> {
                       if (value == LastItem.emptyContainer) {
                         return Container();
                       } else if (value == LastItem.errorIndicator) {
-                        return widget.errorIndicatorWidget(
-                            exception, tryAgain);
+                        return widget.errorIndicatorWidget(exception, tryAgain);
                       }
                       return widget.progressIndicatorWidget;
                     });

lib/src/paginable_sliver_child_builder_delegate.dart

@@ -3,13 +3,25 @@ import 'package:flutter/material.dart';
 import 'package:paginable/src/utils/last_item.dart';
 import 'package:provider/provider.dart';
 
+/// It is the is paginable's version of [SliverChildBuilderDelegate](https://api.flutter.dev/flutter/widgets/SliverChildBuilderDelegate-class.html) and it is used along with [PaginableCustomScrollView](https://pub.dev/packages/paginable#using-paginablecustomscrollview-with-paginablesliverchildbuilderdelegate) to perform pagination.
 class PaginableSliverChildBuilderDelegate {
   static int _kDefaultSemanticIndexCallback(Widget _, int localIndex) =>
       localIndex;
 
   final NullableIndexedWidgetBuilder builder;
+
+  /// It takes a function which contains two parameters, one being of type `Exception` and other being a
+  /// `Function()`, returning a widget which will be displayed at the bottom of the scrollview when an
+  /// exception occurs in the async function which we passed to the `loadMore` parameter.
+  ///
+  /// The parameter with type `Exception` will contain the exception which occured while executing the
+  /// function passed to the parameter `loadMore` if exception occured, and the parameter with type `Function()`
+  /// will contain the same function which we passed to the `loadMore` parameter.
   final Widget Function(Exception exception, void Function() tryAgain)
       errorIndicatorWidget;
+
+  /// It takes a widget which will be displayed at the bottom of the scrollview to indicate the user that
+  /// the async function we passed to the `loadMore` parameter is being executed.
   final Widget progressIndicatorWidget;
   final int? Function(Key)? findChildIndexCallback;
   final int? childCount;
@@ -30,6 +42,13 @@ class PaginableSliverChildBuilderDelegate {
       this.semanticIndexCallback = _kDefaultSemanticIndexCallback,
       this.semanticIndexOffset = 0});
 
+  /// Creates a delegate that supplies children for slivers using the given
+  /// builder callback.
+  ///
+  /// If the order in which [builder] returns children ever changes, consider
+  /// providing a [findChildIndexCallback]. This allows the delegate to find the
+  /// new index for a child that was previously located at a different index to
+  /// attach the existing state to the [Widget] at its new location.
   SliverChildBuilderDelegate build() =>
       SliverChildBuilderDelegate((BuildContext context, int index) {
         if (index == childCount) {

lib/src/utils/last_item.dart

@@ -1,5 +1 @@
-enum LastItem {
-  progressIndicator,
-  errorIndicator,
-  emptyContainer
-}
+enum LastItem { progressIndicator, errorIndicator, emptyContainer }

pubspec.yaml

@@ -1,6 +1,6 @@
 name: paginable
-description: A Flutter package which makes pagination easier.
-version: 1.0.0
+description: Paginable is a Flutter package which makes pagination easier by providing more functionality on top of native widgets.
+version: 1.1.0
 homepage: https://github.com/chinkysight/paginable
 
 environment:
@@ -10,7 +10,7 @@ environment:
 dependencies:
   flutter:
     sdk: flutter
-  provider: ^6.0.0
+  provider: ^6.0.1
 
 dev_dependencies:
   flutter_lints: ^1.0.4

test/paginable_listview_builder_test.dart

@@ -57,7 +57,7 @@ void main() {
 
     final exceptionFinder = find.text(exception.toString());
 
-    bool isRedContainer(Widget widget)=>
+    bool isRedContainer(Widget widget) =>
         widget is Container && widget.color == Colors.redAccent;
 
     expect(exceptionFinder, findsOneWidget);
@@ -79,8 +79,9 @@ void main() {
       scrollToTheEndOfScrollView(scrollController);
       await tester.pump();
 
-      bool isEmptyContainer(Widget widget) => widget is Container && widget.child == null;
-    
+      bool isEmptyContainer(Widget widget) =>
+          widget is Container && widget.child == null;
+
       expect(find.byWidgetPredicate(isEmptyContainer), findsOneWidget);
     });
 
@@ -98,7 +99,8 @@ void main() {
       scrollToTheEndOfScrollView(scrollController);
       await tester.pump(const Duration(seconds: 3));
 
-      bool isEmptyContainer(Widget widget) => widget is Container && widget.child == null;
+      bool isEmptyContainer(Widget widget) =>
+          widget is Container && widget.child == null;
 
       expect(find.byWidgetPredicate(isEmptyContainer), findsOneWidget);
     });

test/paginable_sliver_child_builder_delegate_test.dart

@@ -78,7 +78,8 @@ void main() {
       scrollToTheEndOfScrollView(scrollController);
       await tester.pump();
 
-      bool isEmptyContainer(Widget widget) => widget is Container && widget.child == null;
+      bool isEmptyContainer(Widget widget) =>
+          widget is Container && widget.child == null;
 
       expect(find.byWidgetPredicate(isEmptyContainer), findsOneWidget);
     });
@@ -97,7 +98,8 @@ void main() {
       scrollToTheEndOfScrollView(scrollController);
       await tester.pump(const Duration(seconds: 3));
 
-      bool isEmptyContainer(Widget widget) => widget is Container && widget.child == null;
+      bool isEmptyContainer(Widget widget) =>
+          widget is Container && widget.child == null;
 
       expect(find.byWidgetPredicate(isEmptyContainer), findsOneWidget);
     });