Merge pull request #9 from Iconica-Development/doc/improve-documentation

doc: create documentation for file

README.md

@@ -32,7 +32,7 @@ Please file any issues, bugs or feature request as an issue on our [GitHub](http
 
 ## Want to contribute
 
-If you would like to contribute to the plugin (e.g. by improving the documentation, solving a bug or adding a cool new feature), please carefully review our [contribution guide](../CONTRIBUTING.md) and send us your [pull request](https://github.com/Iconica-Development/flutter_introduction/pulls).
+If you would like to contribute to the plugin (e.g. by improving the documentation, solving a bug or adding a cool new feature), please carefully review our [contribution guide](./CONTRIBUTING.md) and send us your [pull request](https://github.com/Iconica-Development/flutter_introduction/pulls).
 
 ## Author
 

packages/flutter_introduction/lib/flutter_introduction.dart

@@ -19,10 +19,19 @@ class Introduction extends StatefulWidget {
     super.key,
   });
 
+  /// Callback function to navigate to the next screen.
   final VoidCallback navigateTo;
+
+  /// The introduction service to use.
   final IntroductionService? service;
+
+  /// Options for configuring the introduction screen.
   final IntroductionOptions options;
+
+  /// The scrolling physics for the introduction screen.
   final ScrollPhysics? physics;
+
+  /// Child widget to display.
   final Widget? child;
 
   @override

packages/flutter_introduction_interface/lib/src/introduction_interface.dart

@@ -6,20 +6,35 @@ import 'package:flutter_data_interface/flutter_data_interface.dart';
 import 'package:flutter_introduction_interface/src/local_introduction.dart';
 
 abstract class IntroductionInterface extends DataInterface {
+  /// Constructs an instance of [IntroductionInterface].
+  ///
+  /// The [token] is used for verification purposes.
   IntroductionInterface() : super(token: _token);
 
   static final Object _token = Object();
 
   static IntroductionInterface _instance = LocalIntroductionDataProvider();
 
+  /// Retrieves the current instance of [IntroductionInterface].
   static IntroductionInterface get instance => _instance;
 
+  /// Sets the current instance of [IntroductionInterface].
+  ///
+  /// Throws an error if the provided instance does not match the token.
   static set instance(IntroductionInterface instance) {
     DataInterface.verify(instance, _token);
     _instance = instance;
   }
 
+  /// Sets whether the introduction is completed or not.
+  ///
+  /// The [value] parameter specifies whether the introduction is completed.
+  /// By default, it is set to `true`.
   Future<void> setCompleted({bool value = true});
 
+  /// Checks if the introduction should be shown.
+  ///
+  /// Returns `true` if the introduction should be shown;
+  /// otherwise, returns `false`.
   Future<bool> shouldShow();
 }

packages/flutter_introduction_interface/lib/src/local_introduction.dart

@@ -4,9 +4,17 @@
 
 import 'package:flutter_introduction_interface/src/introduction_interface.dart';
 
+/// Provides local data storage for managing introduction data.
+///
+/// This class extends [IntroductionInterface] and implements methods to manage
+/// introduction data locally.
 class LocalIntroductionDataProvider extends IntroductionInterface {
+  /// Constructs an instance of [LocalIntroductionDataProvider].
+  ///
+  /// Initializes the [hasViewed] flag to `false`.
   LocalIntroductionDataProvider();
 
+  /// Flag indicating whether the introduction has been viewed or not.
   bool hasViewed = false;
 
   @override

packages/flutter_introduction_service/lib/src/introduction_service.dart

@@ -4,15 +4,36 @@
 
 import 'package:flutter_introduction_interface/flutter_introduction_interface.dart';
 
+/// A service for managing introduction-related operations.
+///
+/// This class provides methods for handling introduction-related actions
+/// such as skipping, completing,
+/// and determining whether to show the introduction.
 class IntroductionService {
+  /// Constructs an instance of [IntroductionService].
+  ///
+  /// Optionally takes a [dataProvider] parameter,
+  /// which is an implementation of [IntroductionInterface].
+  /// If no data provider is provided,
+  /// it defaults to [LocalIntroductionDataProvider].
   IntroductionService([IntroductionInterface? dataProvider])
       : _dataProvider = dataProvider ?? LocalIntroductionDataProvider();
 
   late final IntroductionInterface _dataProvider;
 
+  /// Marks the introduction as skipped.
+  ///
+  /// Calls [_dataProvider.setCompleted] with the value `true`.
   Future<void> onSkip() => _dataProvider.setCompleted(value: true);
 
+  /// Marks the introduction as completed.
+  ///
+  /// Calls [_dataProvider.setCompleted] with the value `true`.
   Future<void> onComplete() => _dataProvider.setCompleted(value: true);
 
+  /// Checks whether the introduction should be shown.
+  ///
+  /// Returns a `Future<bool>` indicating whether the
+  /// introduction should be shown.
   Future<bool> shouldShow() => _dataProvider.shouldShow();
 }

packages/flutter_introduction_shared_preferences/lib/flutter_introduction_shared_preferences.dart

@@ -5,16 +5,27 @@
 import 'package:flutter_introduction_interface/flutter_introduction_interface.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 
+/// Provides data storage using SharedPreferences for
+/// managing introduction data.
+///
+/// This class extends [IntroductionInterface] and implements methods to manage
+/// introduction data using SharedPreferences.
 class SharedPreferencesIntroductionDataProvider extends IntroductionInterface {
+  /// Constructs an instance of [SharedPreferencesIntroductionDataProvider].
   SharedPreferencesIntroductionDataProvider();
 
   SharedPreferences? _prefs;
   String key = '_completedIntroduction';
 
+  /// Writes a key-value pair to SharedPreferences.
+  ///
+  /// The [key] is the key under which to store the [value].
+  /// The [value] is the boolean value to be stored.
   Future<void> _writeKeyValue(String key, bool value) async {
     await _prefs!.setBool(key, value);
   }
 
+  /// Initializes the SharedPreferences instance.
   Future<void> _init() async {
     _prefs ??= await SharedPreferences.getInstance();
   }

packages/flutter_introduction_widget/lib/src/types/page_introduction.dart

@@ -11,7 +11,12 @@ import 'package:flutter_introduction_widget/src/widgets/background.dart';
 import 'package:flutter_introduction_widget/src/widgets/indicator.dart';
 import 'package:flutter_introduction_widget/src/widgets/page_content.dart';
 
+/// A screen widget for displaying a multi-page introduction.
+///
+/// This widget provides a multi-page introduction experience with options
+/// for handling navigation and completion callbacks.
 class MultiPageIntroductionScreen extends StatefulWidget {
+  /// Creates a new instance of [MultiPageIntroductionScreen].
   const MultiPageIntroductionScreen({
     required this.options,
     required this.onComplete,
@@ -22,12 +27,22 @@ class MultiPageIntroductionScreen extends StatefulWidget {
     super.key,
   });
 
+  /// Callback function triggered when the introduction is completed.
   final VoidCallback onComplete;
-  final VoidCallback? onSkip;
+
+  /// Callback function triggered when the "Next" button is pressed.
   final void Function(IntroductionPage)? onNext;
+
+  /// Callback function triggered when the "Previous" button is pressed.
   final void Function(IntroductionPage)? onPrevious;
+
+  /// Callback function triggered when the "Skip" button is pressed.
+  final VoidCallback? onSkip;
+
+  /// Physics for the scrolling behavior.
   final ScrollPhysics? physics;
 
+  /// Introduction options specifying the configuration of the introduction.
   final IntroductionOptions options;
 
   @override
@@ -35,6 +50,9 @@ class MultiPageIntroductionScreen extends StatefulWidget {
       _MultiPageIntroductionScreenState();
 }
 
+/// State class for [MultiPageIntroductionScreen].
+///
+/// Manages the state and behavior of the [MultiPageIntroductionScreen] widget.
 class _MultiPageIntroductionScreenState
     extends State<MultiPageIntroductionScreen> {
   final PageController _controller = PageController();
@@ -449,16 +467,31 @@ class IntroductionOneButton extends StatelessWidget {
     super.key,
   });
 
+  /// Options specifying the configuration of the introduction.
   final IntroductionOptions options;
+
+  /// Controller for managing the pages of the introduction.
   final PageController controller;
+
+  /// Callback function triggered when the introduction is completed.
   final VoidCallback? onFinish;
+
+  /// Callback function triggered when the "Next" button is pressed.
   final VoidCallback? onNext;
+
+  /// Callback function triggered when the "Previous" button is pressed.
   final VoidCallback? onPrevious;
 
+  /// Indicates whether there are previous pages.
   final bool previous;
+
+  /// Indicates whether there are next pages.
   final bool next;
+
+  /// Indicates whether this is the last page.
   final bool last;
 
+  /// Handles the navigation to the previous page.
   Future<void> _previous() async {
     await controller.previousPage(
       duration: kAnimationDuration,
@@ -585,16 +618,31 @@ class IntroductionIconButtons extends StatelessWidget {
     super.key,
   });
 
+  /// Options specifying the configuration of the introduction.
   final IntroductionOptions options;
+
+  /// Controller for managing the pages of the introduction.
   final PageController controller;
+
+  /// Callback function triggered when the introduction is completed.
   final VoidCallback? onFinish;
+
+  /// Callback function triggered when the "Next" button is pressed.
   final VoidCallback? onNext;
+
+  /// Callback function triggered when the "Previous" button is pressed.
   final VoidCallback? onPrevious;
 
+  /// Indicates whether there are previous pages.
   final bool previous;
+
+  /// Indicates whether there are next pages.
   final bool next;
+
+  /// Indicates whether this is the last page.
   final bool last;
 
+  /// Handles the navigation to the previous page.
   Future<void> _previous() async {
     await controller.previousPage(
       duration: kAnimationDuration,

packages/flutter_introduction_widget/lib/src/types/single_introduction.dart

@@ -6,12 +6,15 @@ import 'package:flutter/cupertino.dart';
 
 import 'package:flutter_introduction_widget/src/config/introduction.dart';
 
+/// Widget representing a single introduction page.
 class SingleIntroductionPage extends StatelessWidget {
+  /// Constructs a [SingleIntroductionPage] widget.
   const SingleIntroductionPage({
     required this.options,
     super.key,
   });
 
+  /// Options specifying the configuration of the introduction.
   final IntroductionOptions options;
 
   @override

packages/flutter_introduction_widget/lib/src/widgets/background.dart

@@ -4,14 +4,19 @@
 
 import 'package:flutter/material.dart';
 
+/// Widget representing a background with optional decoration.
 class Background extends StatelessWidget {
+  /// Constructs a Background widget.
   const Background({
     required this.child,
     this.background,
     super.key,
   });
 
+  /// Optional decoration for the background.
   final BoxDecoration? background;
+
+  /// The widget to be placed on the background.
   final Widget child;
 
   @override

packages/flutter_introduction_widget/lib/src/widgets/indicator.dart

@@ -23,17 +23,22 @@ class Indicator extends StatelessWidget {
           'must be provided',
         );
 
+  /// The mode of the indicator.
   final IndicatorMode mode;
+
+  /// The PageController for which the indicator is displayed.
   final PageController controller;
-  final Widget Function(
-    BuildContext,
-    PageController,
-    int,
-    int,
-  )? indicatorBuilder;
-  final int index;
+
+  /// The total number of items managed by the PageController.
   final int count;
 
+  /// The index of the current item in the PageController.
+  final int index;
+
+  /// Builder function for a custom indicator.
+  final Widget Function(BuildContext, PageController, int, int)?
+      indicatorBuilder;
+
   @override
   Widget build(BuildContext context) {
     var theme = Theme.of(context);
@@ -84,10 +89,20 @@ class DashIndicator extends AnimatedWidget {
     this.color = Colors.white,
     super.key,
   }) : super(listenable: controller);
+
+  /// The PageController for which the indicator is displayed.
   final PageController controller;
+
+  /// The color of the dashes.
   final Color color;
+
+  /// The color of the selected dash.
   final Color selectedColor;
+
+  /// The total number of items managed by the PageController.
   final int itemCount;
+
+  /// Callback function called when a dash is selected.
   final Function(int) onPageSelected;
 
   int _getPage() {

packages/flutter_introduction_widget/lib/src/widgets/page_content.dart

@@ -6,7 +6,9 @@ import 'package:flutter/material.dart';
 
 import 'package:flutter_introduction_widget/src/config/introduction.dart';
 
+/// Widget representing the content of an introduction page.
 class IntroductionPageContent extends StatelessWidget {
+  /// Constructs an IntroductionPageContent widget.
   const IntroductionPageContent({
     required this.title,
     required this.text,
@@ -16,10 +18,19 @@ class IntroductionPageContent extends StatelessWidget {
     super.key,
   });
 
+  /// The title widget.
   final Widget? title;
+
+  /// The text widget.
   final Widget? text;
+
+  /// The graphic widget.
   final Widget? graphic;
+
+  /// The layout style of the content.
   final IntroductionLayoutStyle layoutStyle;
+
+  /// Callback function called when the content is tapped.
   final VoidCallback onTap;
 
   @override