add document for core classes

lib/src/core/toastification.dart

@@ -5,8 +5,74 @@ import 'package:toastification/src/core/toastification_manager.dart';
 import 'package:toastification/src/widget/built_in/built_in.dart';
 import 'package:toastification/src/widget/built_in/built_in_builder.dart';
 
+/// This is the main singleton class instance of the package.
+/// You can use this instance to show and manage your notifications.
+///
+/// use [show] method to show a built-in notifications
+/// example :
+///
+/// ```dart
+/// toastification.show(
+///   context: context,
+///   alignment: Alignment.topRight,
+///   title: 'Hello World',
+///   description: 'This is a notification',
+///   type: ToastificationType.info,
+///   style: ToastificationStyle.floating,
+///   autoCloseDuration: Duration(seconds: 3),
+/// );
+/// ```
+///
+/// use [showCustom] method to show a custom notification
+/// you should create your own widget and pass it to the [builder] parameter
+/// example :
+///
+/// ```dart
+/// toastification.showCustom(
+///   context: context,
+///   alignment: Alignment.topRight,
+///   animationDuration: Duration(milliseconds: 500),
+///   autoCloseDuration: Duration(seconds: 3),
+///   builder: (context, item) {
+///     return CustomToastWidget();
+///   },
+/// );
+/// ```
 final toastification = Toastification();
 
+/// This is the main class of the package.
+/// You can use this class to show and manage your notifications.
+///
+/// use [show] method to show a built-in notifications
+/// example :
+///
+/// ```dart
+/// Toastification().show(
+///   context: context,
+///   alignment: Alignment.topRight,
+///   title: 'Hello World',
+///   description: 'This is a notification',
+///   type: ToastificationType.info,
+///   style: ToastificationStyle.floating,
+///   autoCloseDuration: Duration(seconds: 3),
+/// );
+/// ```
+///
+/// use [showCustom] method to show a custom notification
+/// you should create your own widget and pass it to the [builder] parameter
+/// example :
+///
+/// ```dart
+/// Toastification().showCustom(
+///   context: context,
+///   alignment: Alignment.topRight,
+///   animationDuration: Duration(milliseconds: 500),
+///   autoCloseDuration: Duration(seconds: 3),
+///   builder: (context, item) {
+///     return CustomToastWidget();
+///   },
+/// );
+/// ```
 class Toastification {
   static final Toastification _instance = Toastification._internal();
 
@@ -16,12 +82,46 @@ class Toastification {
 
   final Map<Alignment, ToastificationManager> _managers = {};
 
+  /// the default configuration for the toastification
+  /// 
+  /// when you are using [show] or [showCustom] methods,
+  /// if some of the parameters are not provided,
+  /// [Toastification] will use this class to get the default values.
+  ///
+  /// update this value to change the default configuration of the toastification package
+  ///
+  /// example :
+  ///
+  /// ```dart
+  /// toastification.config = ToastificationConfig(
+  ///   alignment: Alignment.topRight,
+  ///   animationDuration: const Duration(milliseconds: 500),
+  ///   animationBuilder: (context, animation,alignment, child) {
+  ///     return FadeTransition(
+  ///       opacity: animation,
+  ///       child: child,
+  ///     );
+  ///   },
+  /// );
+  /// ```
   ToastificationConfig config = const ToastificationConfig();
 
-  /// using this method you can show a notification
-  /// if there is no notification in the notification list,
-  /// we will animate in the overlay
-  /// otherwise we will just add the notification to the list
+  /// shows a custom notification
+  /// you should create your own widget and pass it to the [builder] parameter
+  ///
+  /// example :
+  ///
+  /// ```dart
+  /// toastification.showCustom(
+  ///   context: context,
+  ///   alignment: Alignment.topRight,
+  ///   animationDuration: Duration(milliseconds: 500),
+  ///   autoCloseDuration: Duration(seconds: 3),
+  ///   builder: (context, item) {
+  ///     return CustomToastWidget();
+  ///   },
+  /// );
+  /// ```
   ToastificationItem showCustom({
     required BuildContext context,
     AlignmentGeometry? alignment,
@@ -51,6 +151,19 @@ class Toastification {
   }
 
   /// using this method you can show a notification by using the [navigator] overlay
+  /// you should create your own widget and pass it to the [builder] parameter
+  ///
+  /// ```dart
+  /// toastification.showWithNavigatorState(
+  ///   navigator: navigatorState or Navigator.of(context),
+  ///   alignment: Alignment.topRight,
+  ///   animationDuration: Duration(milliseconds: 500),
+  ///   autoCloseDuration: Duration(seconds: 3),
+  ///   builder: (context, item) {
+  ///     return CustomToastWidget();
+  ///   },
+  /// );
+  /// ```
   ToastificationItem showWithNavigatorState({
     required NavigatorState navigator,
     required ToastificationBuilder builder,
@@ -72,6 +185,22 @@ class Toastification {
     );
   }
 
+  /// shows a built-in notification with the given parameters
+  ///
+  /// example :
+  ///
+  /// ```dart
+  /// toastification.show(
+  ///   context: context,
+  ///   alignment: Alignment.topRight,
+  ///   title: 'Hello World',
+  ///   description: 'This is a notification',
+  ///   type: ToastificationType.info,
+  ///   style: ToastificationStyle.floating,
+  ///   autoCloseDuration: Duration(seconds: 3),
+  /// );
+  /// ```
+  ///
   ToastificationItem show({
     required BuildContext context,
     AlignmentGeometry? alignment,
@@ -129,6 +258,9 @@ class Toastification {
     );
   }
 
+  /// finds and returns a [ToastificationItem] by its [id]
+  ///
+  /// if there is no notification with the given [id] it will return null
   ToastificationItem? findToastificationItem(String id) {
     try {
       for (final manager in _managers.values) {
@@ -145,9 +277,9 @@ class Toastification {
     return null;
   }
 
-  /// using this method you can remove a notification
-  /// if there is no notification in the notification list,
-  /// we will remove the overlay entry
+  /// dismisses the given [notification]
+  ///
+  /// if the [notification] is not in the list, nothing will happen
   void dismiss(ToastificationItem notification) {
     final manager = _managers[notification.alignment];
 
@@ -156,17 +288,19 @@ class Toastification {
     }
   }
 
-  /// This function dismisses all the notifications in the [_notifications] list.
-  /// The delayForAnimation parameter is optional and defaults to true.
-  /// When true, it adds a delay for better animation.
+  /// dismisses all notifications that are currently showing in the screen
+  ///
+  /// The [delayForAnimation] parameter is used to determine
+  /// whether to wait for the animation to finish or not.
   void dismissAll({bool delayForAnimation = true}) {
     for (final manager in _managers.values) {
       manager.dismissAll(delayForAnimation: delayForAnimation);
     }
   }
 
-  /// remove a notification by its [id]
-  /// if there is no notification with the given [id], nothing will happen
+  /// dismisses a notification by its [id]
+  ///
+  /// if there is no notification with the given [id] nothing will happen
   void dismissById(String id) {
     final notification = findToastificationItem(id);
 

lib/src/core/toastification_config.dart

@@ -4,6 +4,14 @@ import 'package:toastification/toastification.dart';
 const _defaultAlignment = AlignmentDirectional.topEnd;
 const _itemAnimationDuration = Duration(milliseconds: 300);
 
+/// you can use [ToastificationConfig] class to change default values of [Toastification]
+/// 
+/// when you are using [show] or [showCustom] methods, 
+/// if some of the parameters are not provided,
+/// 
+/// [Toastification] will use this class to get the default values.
+/// 
+
 class ToastificationConfig {
   const ToastificationConfig({
     this.alignment = _defaultAlignment,

lib/src/core/toastification_item.dart

@@ -2,6 +2,15 @@ import 'package:flutter/cupertino.dart';
 import 'package:pausable_timer/pausable_timer.dart';
 import 'package:uuid/uuid.dart';
 
+const _uuid = Uuid();
+
+/// enum to define the status of the timer of the toastification item
+/// [init] : the timer is not started yet
+/// [started] : the timer is started
+/// [paused] : the timer is paused
+/// [stopped] : the timer is stopped
+/// [finished] : the timer is finished
+///
 enum ToastTimeStatus {
   init,
   started,
@@ -10,20 +19,32 @@ enum ToastTimeStatus {
   finished,
 }
 
-var uuid = const Uuid();
-
+/// type definition for the builder of the custom toastification
+/// use this builder to create your own toastification widget
 typedef ToastificationBuilder = Widget Function(
   BuildContext context,
   ToastificationItem holder,
 );
 
+/// type definition for the animation builder of the custom toastification
+/// use this builder to create your own toastification animation
 typedef ToastificationAnimationBuilder = Widget Function(
   BuildContext context,
   Animation<double> animation,
   Alignment alignment,
   Widget child,
 );
 
+/// class to define the toastification item
+/// this class is the base model for the toastification item
+///
+/// * do not create an instance of this class directly
+/// [Toastification] class is responsible for creating an instance of this class
+///
+/// this class will be returned when you call [show] or [showCustom] methods
+///
+/// you can also use this class to control the toastification items
+///
 class ToastificationItem {
   ToastificationItem({
     required this.builder,
@@ -32,7 +53,7 @@ class ToastificationItem {
     this.animationDuration,
     this.autoCloseDuration,
     void Function(ToastificationItem holder)? onAutoCompleteCompleted,
-  }) : id = uuid.v4() {
+  }) : id = _uuid.v4() {
     if (autoCloseDuration != null) {
       _timer = PausableTimer(
         autoCloseDuration!,
@@ -48,61 +69,88 @@ class ToastificationItem {
     }
   }
 
+  /// unique id for the toastification item
+  /// this id will be used to identify the toastification item
   final String id;
 
+  /// the alignment of the toastification item
+  /// this alignment will be used to define the position of the toastification item in the screen
   final Alignment alignment;
 
+  /// the duration of the auto close timer
+  /// if the [autoCloseDuration] is provided then the timer will be created
+  /// and the toastification item will be dismissed automatically after the [autoCloseDuration] is finished
   final Duration? autoCloseDuration;
 
+  /// the builder of the toastification item
+  /// this builder will be used to create the toastification item widget
   final ToastificationBuilder builder;
 
+  /// the animation builder of the toastification item
   final ToastificationAnimationBuilder? animationBuilder;
 
+  /// the animation duration of the toastification item animation
   final Duration? animationDuration;
 
   late final PausableTimer? _timer;
 
   final ValueNotifier<ToastTimeStatus> _timeStatus =
       ValueNotifier(ToastTimeStatus.init);
 
+  /// the status of the timer
   ToastTimeStatus get timeStatus => _timeStatus.value;
 
-  Duration? get currentDuration => _timer?.duration;
+  /// The original duration this timer was created with.
+  Duration? get originalDuration => _timer?.duration;
+
+  /// the amount of the time that timer has been running for.
+  ///
+  /// If the timer is paused, the elapsed time is also not computed anymore, so
+  /// [elapsed] is always less than or equals to the [duration].  Duration? get elapsedDuration => _timer?.elapsed;
   Duration? get elapsedDuration => _timer?.elapsed;
 
+  /// checks if the [autoCloseDuration] is provided or not
+  /// if the [autoCloseDuration] is provided then the timer will be created
   bool get hasTimer => _timer != null;
 
+  /// checks if the timer is running or not
   bool get isRunning =>
       _timeStatus.value == ToastTimeStatus.started ||
       _timeStatus.value == ToastTimeStatus.paused;
 
+  /// checks if the timer is started or not
   bool get isStarted => _timeStatus.value == ToastTimeStatus.started;
 
+  /// starts the timer
   void start() {
     if (hasTimer) {
       _timer?.start();
       _timeStatus.value = ToastTimeStatus.started;
     }
   }
 
+  /// pauses the timer
   void pause() {
     if (hasTimer) {
       _timer?.pause();
       _timeStatus.value = ToastTimeStatus.paused;
     }
   }
 
+  /// stops the timer
   void stop() {
     if (hasTimer) {
       _timer?.cancel();
       _timeStatus.value = ToastTimeStatus.stopped;
     }
   }
 
+  /// add a listener to the timer status notifier
   void addListenerOnTimeStatus(VoidCallback listener) {
     _timeStatus.addListener(listener);
   }
 
+  /// remove a listener from the timer status notifier
   void removeListenerOnTimeStatus(VoidCallback listener) {
     _timeStatus.removeListener(listener);
   }
@@ -123,6 +171,6 @@ class ToastificationItem {
 
   @override
   String toString() {
-    return 'id: $id, timerDuration: $currentDuration, elapsedDuration: $elapsedDuration';
+    return 'id: $id, timerDuration: $originalDuration, elapsedDuration: $elapsedDuration';
   }
 }