chore: 📝 Improve documentation

lib/src/application/ae_token.dart

@@ -6,23 +6,42 @@ import 'package:riverpod_annotation/riverpod_annotation.dart';
 
 part 'ae_token.g.dart';
 
+/// Estimates the value of a token in fiat currency.
+///
+/// This provider fetches the token's price in USD based on its symbol and address.
+/// - If the token's symbol is `UCO`, the price is fetched using the Archethic Oracle.
+/// - For other tokens, the price is fetched using the Coin Price provider.
+///
+/// Example:
+/// ```dart
+/// final priceInFiat = await ref.read(estimateTokenInFiatProvider(token));
+/// ```
 @riverpod
 Future<double> _estimateTokenInFiat(
   Ref ref,
   AEToken token,
 ) async {
   if (token.symbol == 'UCO') {
+    // Fetch the UCO price from the Archethic Oracle.
     final archethicOracleUCO =
         ref.watch(aedappfm.ArchethicOracleUCOProviders.archethicOracleUCO);
 
     return archethicOracleUCO.usd;
   } else {
+    // Fetch the token price from the Coin Price provider.
     return await ref.watch(
       aedappfm.CoinPriceProviders.coinPrice(address: token.address!).future,
     );
   }
 }
 
+/// A collection of providers for managing AEToken-related functionalities.
+///
+/// Example usage:
+/// ```dart
+/// final priceInFiat = await ref.read(AETokensProviders.estimateTokenInFiat(token));
+/// ```
 abstract class AETokensProviders {
+  /// Provider to estimate the fiat value of a token.
   static const estimateTokenInFiat = _estimateTokenInFiatProvider;
 }

lib/src/application/coin_price.dart

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+
 import 'dart:async';
 
 import 'package:archethic_dapp_framework_flutter/archethic_dapp_framework_flutter.dart';
@@ -8,21 +9,33 @@ import 'package:riverpod_annotation/riverpod_annotation.dart';
 
 part 'coin_price.g.dart';
 
+/// A notifier responsible for managing and updating cryptocurrency prices.
+///
+/// This notifier fetches cryptocurrency prices from the repository at
+/// regular intervals (1 minute) and updates the state with the latest prices.
 @riverpod
 class _CoinPricesNotifier extends _$CoinPricesNotifier {
   static final _logger = Logger('CoinPricesNotifier');
 
+  /// A timer to periodically fetch prices.
   Timer? _timer;
 
+  /// Builds the initial state and starts the periodic price update timer.
   @override
   CryptoPrice build() {
+    // Ensure the timer stops when the notifier is disposed.
     ref.onDispose(stopTimer);
 
+    // Start fetching prices periodically.
     startTimer();
 
+    // Return an empty initial state.
     return CryptoPrice();
   }
 
+  /// Starts the periodic price fetch timer.
+  ///
+  /// The prices are updated every minute using the repository.
   Future<void> startTimer() async {
     if (_timer != null) return;
 
@@ -33,6 +46,7 @@ class _CoinPricesNotifier extends _$CoinPricesNotifier {
     });
   }
 
+  /// Stops the periodic price fetch timer.
   Future<void> stopTimer() async {
     _logger.info('Stop timer');
     if (_timer == null) return;
@@ -41,22 +55,37 @@ class _CoinPricesNotifier extends _$CoinPricesNotifier {
   }
 }
 
+/// Provides an instance of [CoinPriceRepositoryImpl].
+///
+/// This repository is used to fetch cryptocurrency prices from an external source.
 @riverpod
 CoinPriceRepositoryImpl _coinPriceRepository(
   Ref ref,
 ) =>
     CoinPriceRepositoryImpl();
 
+/// Fetches the price of a cryptocurrency based on its address.
+///
+/// This provider retrieves the token's UCID and uses it to find the corresponding price.
+/// If the UCID cannot be resolved, the price defaults to 0.
+///
+/// Example usage:
+/// ```dart
+/// final price = await ref.read(coinPriceProvider(address: 'some-address').future);
+/// ```
 @riverpod
 Future<double> _coinPrice(
   Ref ref, {
   required String address,
   Environment? environment,
 }) async {
   try {
+    // Fetch the latest cryptocurrency prices.
     final coinPrice = ref.watch(
       CoinPriceProviders.coinPrices,
     );
+
+    // Resolve the UCID for the given address and environment.
     final ucid = await ref.watch(
       UcidsTokensProviders.ucid(
         address: address.toUpperCase(),
@@ -67,15 +96,25 @@ Future<double> _coinPrice(
     if (ucid == null) {
       return 0;
     }
+
+    // Fetch the price for the resolved UCID.
     return ref
         .watch(_coinPriceRepositoryProvider)
         .getPriceFromUcid(ucid, coinPrice);
   } catch (e) {
+    // Return 0 in case of an error.
     return 0;
   }
 }
 
+/// A collection of providers for managing cryptocurrency prices.
+///
+/// This class centralizes providers related to cryptocurrency price fetching
+/// and management, making them easier to access and organize.
 abstract class CoinPriceProviders {
+  /// A provider that manages and updates cryptocurrency prices periodically.
   static final coinPrices = _coinPricesNotifierProvider;
+
+  /// A provider that fetches the price of a specific cryptocurrency.
   static const coinPrice = _coinPriceProvider;
 }

lib/src/application/oracle/state.dart

@@ -5,8 +5,13 @@ import 'package:freezed_annotation/freezed_annotation.dart';
 part 'state.freezed.dart';
 part 'state.g.dart';
 
+/// A JSON converter for [ArchethicOracleUCO].
+///
+/// This converter handles the serialization and deserialization of
+/// [ArchethicOracleUCO] instances to and from JSON.
 class ArchethicOracleUCOJsonConverter
     extends JsonConverter<ArchethicOracleUCO, Map<String, dynamic>> {
+  /// Creates a new [ArchethicOracleUCOJsonConverter].
   const ArchethicOracleUCOJsonConverter();
 
   @override
@@ -18,14 +23,41 @@ class ArchethicOracleUCOJsonConverter
   Map<String, dynamic> toJson(ArchethicOracleUCO object) => object.toJson();
 }
 
+/// Represents the UCO price information provided by the Archethic Oracle.
+///
+/// This class includes information about the price of UCO in various fiat
+/// currencies, such as EUR and USD, along with a timestamp indicating
+/// when the data was retrieved.
+///
+/// Example:
+/// ```dart
+/// final ucoData = ArchethicOracleUCO(
+///   timestamp: 1672531199,
+///   eur: 10.5,
+///   usd: 12.3,
+/// );
+/// ```
 @freezed
 class ArchethicOracleUCO with _$ArchethicOracleUCO {
+  /// Creates a new [ArchethicOracleUCO] instance.
+  ///
+  /// [timestamp] represents the time when the data was retrieved (in UNIX format).
+  /// [eur] and [usd] represent the price of UCO in Euros and US Dollars, respectively.
   const factory ArchethicOracleUCO({
+    /// The timestamp (UNIX format) when the data was retrieved.
     @Default(0) int timestamp,
+
+    /// The price of UCO in Euros.
     @Default(0) double eur,
+
+    /// The price of UCO in US Dollars.
     @Default(0) double usd,
   }) = _ArchethicOracleUCO;
 
+  /// Creates an [ArchethicOracleUCO] instance from a JSON object.
+  ///
+  /// This factory method is used for deserializing JSON data into
+  /// an [ArchethicOracleUCO] instance.
   factory ArchethicOracleUCO.fromJson(Map<String, dynamic> json) =>
       _$ArchethicOracleUCOFromJson(json);
 }

lib/src/domain/models/ae_token.dart

@@ -5,6 +5,7 @@ import 'package:freezed_annotation/freezed_annotation.dart';
 part 'ae_token.freezed.dart';
 part 'ae_token.g.dart';
 
+/// Provides JSON conversion for [AEToken].
 class AETokenJsonConverter
     implements JsonConverter<AEToken, Map<String, dynamic>> {
   const AETokenJsonConverter();
@@ -18,29 +19,56 @@ class AETokenJsonConverter
   Map<String, dynamic> toJson(AEToken object) => object.toJson();
 }
 
+/// A class representing a token in the Archethic network.
 @freezed
 class AEToken with _$AEToken {
+  /// Creates an [AEToken] instance.
+  ///
+  /// The [name], [symbol], [balance], [reserve], and [supply] have default values.
+  /// If no [address] or [ucid] is provided, they will remain null.
   const factory AEToken({
+    /// The name of the token.
     @Default('') String name,
+
+    /// The address of the token on the Archethic blockchain.
     String? address,
+
+    /// The icon URL or path representing the token.
     String? icon,
+
+    /// The symbol of the token.
     @Default('') String symbol,
+
+    /// The current balance of the token.
     @Default(0.0) double balance,
+
+    /// The reserve balance of the token.
     @Default(0.0) double reserve,
+
+    /// The total supply of the token.
     @Default(0.0) double supply,
+
+    /// Indicates if the token is verified.
     @Default(false) bool isVerified,
+
+    /// Indicates if the token is a liquidity provider token.
     @Default(false) bool isLpToken,
+
+    /// The pair of tokens for LP tokens.
     @AETokenPairJsonConverter() AETokenPair? lpTokenPair,
     int? ucid,
   }) = _AEToken;
   const AEToken._();
 
+  /// Creates an [AEToken] instance from a JSON object.
   factory AEToken.fromJson(Map<String, dynamic> json) =>
       _$AETokenFromJson(json);
 
+  /// Determines if the token is the Archethic Universal Coin (UCO).
   bool get isUCO => symbol == 'UCO' && (address == null || address! == 'UCO');
 }
 
+/// A constant instance of the Archethic Universal Coin (UCO) token.
 AEToken get ucoToken => const AEToken(
       name: 'Universal Coin',
       symbol: 'UCO',

lib/src/domain/models/ae_token_pair.dart

@@ -5,8 +5,13 @@ import 'package:freezed_annotation/freezed_annotation.dart';
 part 'ae_token_pair.freezed.dart';
 part 'ae_token_pair.g.dart';
 
+/// A JSON converter for [AETokenPair].
+///
+/// This class is responsible for serializing and deserializing [AETokenPair]
+/// instances to and from JSON format.
 class AETokenPairJsonConverter
     implements JsonConverter<AETokenPair, Map<String, dynamic>> {
+  /// Creates an instance of [AETokenPairJsonConverter].
   const AETokenPairJsonConverter();
 
   @override
@@ -18,15 +23,35 @@ class AETokenPairJsonConverter
   Map<String, dynamic> toJson(AETokenPair object) => object.toJson();
 }
 
+/// Represents a pair of tokens in the Archethic blockchain ecosystem.
+///
+/// This class is used to model two tokens that are part of a liquidity pair
+/// or any other relationship requiring two tokens.
+///
+/// Example:
+/// ```dart
+/// final pair = AETokenPair(
+///   token1: AEToken(name: 'Token 1', symbol: 'TKN1'),
+///   token2: AEToken(name: 'Token 2', symbol: 'TKN2'),
+/// );
+/// ```
 @freezed
 class AETokenPair with _$AETokenPair {
+  /// Creates an [AETokenPair] instance.
+  ///
+  /// Both [token1] and [token2] must be provided and are required to be of type [AEToken].
+
   const factory AETokenPair({
+    /// The first token in the pair.
     @AETokenJsonConverter() required AEToken token1,
+
+    /// The second token in the pair.
     @AETokenJsonConverter() required AEToken token2,
   }) = _AETokenPair;
 
   const AETokenPair._();
 
+  /// Creates an [AETokenPair] instance from a JSON object.
   factory AETokenPair.fromJson(Map<String, dynamic> json) =>
       _$AETokenPairFromJson(json);
 }

lib/src/domain/models/crypto_price.dart

@@ -3,18 +3,54 @@ import 'package:freezed_annotation/freezed_annotation.dart';
 part 'crypto_price.freezed.dart';
 part 'crypto_price.g.dart';
 
+/// Represents the price data for various cryptocurrencies.
+///
+/// This class provides a structured representation of cryptocurrency prices
+/// at a specific point in time. The prices include Bitcoin, Matic (Pol), Ethereum,
+/// Binance Coin (BNB), USD Coin (USDC), and EURE.
+///
+/// Example:
+/// ```dart
+/// final price = CryptoPrice(
+///   timestamp: 1672531199,
+///   bitcoin: 40000.0,
+///   matic: 1.5,
+///   ethereum: 2500.0,
+///   bnb: 350.0,
+///   usdc: 1.0,
+///   eure: 1.1,
+/// );
+/// ```
 @freezed
 class CryptoPrice with _$CryptoPrice {
+  /// Creates a [CryptoPrice] instance.
+  ///
+  /// The [timestamp] represents the time when the price data was recorded.
+  /// All cryptocurrency prices default to `0.0` if not specified.
   factory CryptoPrice({
+    /// The timestamp of the price data, represented as a UNIX timestamp.
     int? timestamp,
+
+    /// The price of Bitcoin (BTC) in USD or the relevant currency.
     @Default(0.0) double bitcoin,
+
+    /// The price of Matic (Polygon) in USD or the relevant currency.
     @Default(0.0) double matic,
+
+    /// The price of Ethereum (ETH) in USD or the relevant currency.
     @Default(0.0) double ethereum,
+
+    /// The price of Binance Coin (BNB) in USD or the relevant currency.
     @Default(0.0) double bnb,
+
+    /// The price of USD Coin (USDC) in USD or the relevant currency.
     @Default(0.0) double usdc,
+
+    /// The price of EURE (a euro-backed stablecoin) in USD or the relevant currency.
     @Default(0.0) double eure,
   }) = _CryptoPrice;
 
+  /// Creates a [CryptoPrice] instance from a JSON object.
   factory CryptoPrice.fromJson(Map<String, dynamic> json) =>
       _$CryptoPriceFromJson(json);
 }