doc: added more documentation

lib/flutter_quill_delta_from_html.dart

@@ -1,5 +1,7 @@
 library flutter_quill_delta_from_html;
 
+export 'package:flutter_quill_delta_from_html/parser/font_size_parser.dart';
+export 'package:flutter_quill_delta_from_html/parser/line_height_parser.dart';
 export 'package:flutter_quill_delta_from_html/parser/html_to_delta.dart';
 export 'package:flutter_quill_delta_from_html/parser/colors.dart';
 export 'package:flutter_quill_delta_from_html/parser/custom_html_part.dart';

lib/parser/colors.dart

@@ -1,11 +1,47 @@
-///validate the string color to avoid unsupported colors
+/// Validates and retrieves the color string in hexadecimal format.
+///
+/// If [colorString] starts with '#', it's assumed to be already in hexadecimal format.
+/// Otherwise, attempts to convert [colorString] to hexadecimal format using supported color formats.
+/// Throws [ArgumentError] if the color format is not supported.
+///
+/// Parameters:
+/// - [colorString]: The input color string to validate and convert.
+///
+/// Returns:
+/// The validated color string in hexadecimal format.
+///
+/// Example:
+/// ```dart
+/// print(validateAndGetColor('#ff0000')); // Output: #ff0000
+/// print(validateAndGetColor('rgb(255, 0, 0)')); // Output: #ff0000
+/// print(validateAndGetColor('hsl(0, 100%, 50%)')); // Output: #ff0000
+/// ```
 String validateAndGetColor(String colorString) {
   //verify if the color already is a hex
   if (colorString.startsWith('#')) return colorString;
   return colorToHex(colorString);
 }
 
-///Decide the color format type and parse to hex
+/// Decides the color format type and converts it to hexadecimal format.
+///
+/// Detects the type of color from [color] and calls the corresponding conversion function:
+/// - If [color] starts with 'rgb(', converts it using [rgbToHex].
+/// - If [color] starts with 'rgba(', converts it using [rgbaToHex].
+/// - If [color] starts with 'hsl(', converts it using [hslToHex].
+/// - If [color] starts with 'hsla(', converts it using [hslaToHex].
+/// Throws [ArgumentError] if the color format is not supported.
+///
+/// Parameters:
+/// - [color]: The input color string to convert to hexadecimal format.
+///
+/// Returns:
+/// The converted color string in hexadecimal format.
+///
+/// Example:
+/// ```dart
+/// print(colorToHex('rgb(255, 0, 0)')); // Output: #ff0000
+/// print(colorToHex('hsla(0, 100%, 50%, 0.5)')); // Output: #ff0000
+/// ```
 String colorToHex(String color) {
   // Detectar el tipo de color y llamar a la función correspondiente
   if (color.startsWith('rgb(')) {
@@ -21,7 +57,21 @@ String colorToHex(String color) {
   }
 }
 
-///Parse RGB to valid hex string
+
+/// Parses an RGB color string to a valid hexadecimal color string.
+///
+/// Converts the RGB color format string [rgb] (e.g., 'rgb(255, 0, 0)') to its hexadecimal representation.
+///
+/// Parameters:
+/// - [rgb]: The RGB color string to convert to hexadecimal format.
+///
+/// Returns:
+/// The converted color string in hexadecimal format.
+///
+/// Example:
+/// ```dart
+/// print(rgbToHex('rgb(255, 0, 0)')); // Output: #ff0000
+/// ```
 String rgbToHex(String rgb) {
   rgb = rgb.replaceAll('rgb(', '').replaceAll(')', '');
   List<String> rgbValues = rgb.split(',');
@@ -31,7 +81,20 @@ String rgbToHex(String rgb) {
   return _toHex(r, g, b, 255);
 }
 
-///Parse RGBA to valid hex string
+/// Parses an RGBA color string to a valid hexadecimal color string.
+///
+/// Converts the RGBA color format string [rgba] (e.g., 'rgba(255, 0, 0, 0.5)') to its hexadecimal representation.
+///
+/// Parameters:
+/// - [rgba]: The RGBA color string to convert to hexadecimal format.
+///
+/// Returns:
+/// The converted color string in hexadecimal format.
+///
+/// Example:
+/// ```dart
+/// print(rgbaToHex('rgba(255, 0, 0, 0.5)')); // Output: #ff000080
+/// ```
 String rgbaToHex(String rgba) {
   rgba = rgba.replaceAll('rgba(', '').replaceAll(')', '');
   List<String> rgbaValues = rgba.split(',');
@@ -43,7 +106,20 @@ String rgbaToHex(String rgba) {
   return _toHex(r, g, b, alpha);
 }
 
-///Parse hsl to valid hex string
+/// Parses an HSL color string to a valid hexadecimal color string.
+///
+/// Converts the HSL color format string [hsl] (e.g., 'hsl(0, 100%, 50%)') to its hexadecimal representation.
+///
+/// Parameters:
+/// - [hsl]: The HSL color string to convert to hexadecimal format.
+///
+/// Returns:
+/// The converted color string in hexadecimal format.
+///
+/// Example:
+/// ```dart
+/// print(hslToHex('hsl(0, 100%, 50%)')); // Output: #ff0000
+/// ```
 String hslToHex(String hsl) {
   hsl = hsl.replaceAll('hsl(', '').replaceAll(')', '');
   List<String> hslValues = hsl.split(',');
@@ -54,7 +130,20 @@ String hslToHex(String hsl) {
   return _toHex(rgb[0], rgb[1], rgb[2], 255);
 }
 
-///Parse hsla to valid hex string
+/// Parses an HSLA color string to a valid hexadecimal color string.
+///
+/// Converts the HSLA color format string [hsla] (e.g., 'hsla(0, 100%, 50%, 0.5)') to its hexadecimal representation.
+///
+/// Parameters:
+/// - [hsla]: The HSLA color string to convert to hexadecimal format.
+///
+/// Returns:
+/// The converted color string in hexadecimal format.
+///
+/// Example:
+/// ```dart
+/// print(hslaToHex('hsla(0, 100%, 50%, 0.5)')); // Output: #ff000080
+/// ```
 String hslaToHex(String hsla) {
   hsla = hsla.replaceAll('hsla(', '').replaceAll(')', '');
   List<String> hslaValues = hsla.split(',');
@@ -67,7 +156,22 @@ String hslaToHex(String hsla) {
   return _toHex(rgb[0], rgb[1], rgb[2], alpha);
 }
 
-///Ensure parse hsl to rgb string to make more simple convertion to hex
+/// Converts HSL (Hue, Saturation, Lightness) values to RGB (Red, Green, Blue) values.
+///
+/// Converts the HSL color values [h], [s], and [l] to RGB values.
+///
+/// Parameters:
+/// - [h]: Hue value (0-360).
+/// - [s]: Saturation value (0-1).
+/// - [l]: Lightness value (0-1).
+///
+/// Returns:
+/// A list of integers representing the RGB values ([red, green, blue]).
+///
+/// Example:
+/// ```dart
+/// print(_hslToRgb(0, 1.0, 0.5)); // Output: [255, 0, 0] (Equivalent to #ff0000)
+/// ```
 List<int> _hslToRgb(double h, double s, double l) {
   double c = (1 - (2 * l - 1).abs()) * s;
   double x = c * (1 - ((h / 60) % 2 - 1).abs());
@@ -101,7 +205,24 @@ List<int> _hslToRgb(double h, double s, double l) {
   return [red, green, blue];
 }
 
-///Conver RGBA values to hex
+
+/// Converts RGB (Red, Green, Blue) values to a hexadecimal color string.
+///
+/// Converts the RGB values [r], [g], [b], and optional [a] (alpha) to a hexadecimal color string.
+///
+/// Parameters:
+/// - [r]: Red value (0-255).
+/// - [g]: Green value (0-255).
+/// - [b]: Blue value (0-255).
+/// - [a]: Alpha value (0-255), optional. Defaults to 255 (fully opaque).
+///
+/// Returns:
+/// The converted color string in hexadecimal format.
+///
+/// Example:
+/// ```dart
+/// print(_toHex(255, 0, 0, 255)); // Output: #ff0000
+/// ```
 String _toHex(int r, int g, int b, int a) {
   String hexR = r.toRadixString(16).padLeft(2, '0');
   String hexG = g.toRadixString(16).padLeft(2, '0');

lib/parser/custom_html_part.dart

@@ -1,16 +1,47 @@
 import 'package:dart_quill_delta/dart_quill_delta.dart';
 import 'package:html/dom.dart' as dom;
 
-/// Interface for defining a custom block handler.
+/// Interface for defining a custom block handler for HTML to Delta conversion.
 abstract class CustomHtmlPart {
   /// Determines if this custom block handler matches the given HTML element.
-  /// If you want to detect, by example, a `<div>` you need to make something like
-  /// `element.localName == 'div'` 
-  /// And this just will match with any `<div>` tag
+  ///
+  /// Implement this method to specify the conditions under which this handler
+  /// should be used to convert an HTML element to Delta operations.
+  ///
+  /// Parameters:
+  /// - [element]: The HTML element to evaluate.
+  ///
+  /// Returns:
+  /// `true` if this handler should be used for the given HTML element, `false` otherwise.
+  ///
+  /// Example:
+  /// ```dart
+  /// class MyCustomBlock implements CustomHtmlPart {
+  ///   bool matches(dom.Element element) {
+  ///     return element.localName == 'div' && element.classes.contains('my-custom-class');
+  ///   }
+  /// }
+  /// ```
   bool matches(dom.Element element);
 
-  /// Converts the `HTML` element into `Delta` operations.
-  /// It's called when `matches` return true
-  List<Operation> convert(dom.Element element,
-      {Map<String, dynamic>? currentAttributes});
+  /// Converts the HTML element into Delta operations.
+  ///
+  /// Implement this method to convert the matched HTML element into a list of Delta operations.
+  ///
+  /// Parameters:
+  /// - [element]: The HTML element to convert.
+  /// - [currentAttributes]: Optional. The current attributes to apply to the Delta operations.
+  ///
+  /// Returns:
+  /// A list of Delta operations representing the converted content of the HTML element.
+  ///
+  /// Example:
+  /// ```dart
+  /// class MyCustomBlock implements CustomHtmlPart {
+  ///   List<Operation> convert(dom.Element element, {Map<String, dynamic>? currentAttributes}) {
+  ///     // Conversion logic here
+  ///   }
+  /// }
+  /// ```
+  List<Operation> convert(dom.Element element, {Map<String, dynamic>? currentAttributes});
 }

lib/parser/html_to_delta.dart

@@ -5,12 +5,32 @@ import 'package:html/parser.dart' as dparser;
 
 /// Default converter for html to Delta
 class HtmlToDelta {
-  ///Defines all custom blocks for non common html tags
+  /// List of custom HTML parts to handle non-common HTML tags.
+  ///
+  /// These custom blocks define how to convert specific HTML tags into Delta operations.
+  ///
+  /// Example:
+  /// ```dart
+  /// final converter = HtmlToDelta(customBlocks: [
+  ///   MyCustomHtmlPart(
+  ///     matches: (element) => element.localName == 'my-custom-tag',
+  ///     convert: (element) {
+  ///       return [
+  ///         Operation.insert({"custom-tag": element.text})
+  ///       ];
+  ///     },
+  ///   ),
+  /// ]);
+  /// ```
   final List<CustomHtmlPart>? customBlocks;
 
-  ///Defines how will be builded the common tags to Delta Operations
+  /// Converts HTML tags to Delta operations based on defined rules.
   late HtmlOperations htmlToOp;
 
+  /// Creates a new instance of HtmlToDelta.
+  ///
+  /// [htmlToOperations] defines how common HTML tags are converted to Delta operations.
+  /// [customBlocks] allows adding custom rules for handling specific HTML tags.
   HtmlToDelta({
     HtmlOperations? htmlToOperations,
     this.customBlocks,
@@ -20,11 +40,22 @@ class HtmlToDelta {
     htmlToOp.setCustomBlocks(customBlocks ?? []);
   }
 
-  /// Converts HTML text into Delta operations.
+  /// Converts an HTML string into Delta operations.
+  ///
+  /// Converts the HTML string [htmlText] into Delta operations using QuillJS-compatible attributes.
+  /// Custom blocks can be applied based on registered [customBlocks].
+  ///
+  /// Parameters:
+  /// - [htmlText]: The HTML string to convert into Delta operations.
+  ///
+  /// Returns:
+  /// A Delta object representing the formatted content from HTML.
   ///
-  /// Takes an HTML string [htmlText] and converts it into Delta operations using
-  /// QuillJS-compatible attributes. Custom blocks can be applied based on registered
-  /// [customBlocks]. Returns a Delta object representing the formatted content
+  /// Example:
+  /// ```dart
+  /// final delta = converter.convert('<p>Hello <strong>world</strong></p>');
+  /// print(delta.toJson()); // Output: [{"insert":"Hello "},{"insert":"world","attributes":{"bold":true}},{"insert":"\n"}]
+  /// ```
   Delta convert(String htmlText) {
     final Delta delta = Delta();
     final dom.Document $document = dparser.parse(htmlText);
@@ -60,12 +91,23 @@ class HtmlToDelta {
     return delta;
   }
 
-  /// Converts a full DOM document [document] into Delta operations.
+  /// Converts a full DOM document into Delta operations.
   ///
-  /// Processes the entire DOM document [document] and converts its nodes into Delta
-  /// operations using QuillJS-compatible attributes. Custom blocks can be applied
-  /// based on registered [customBlocks]. Returns a Delta object representing the
-  /// formatted content.
+  /// Processes the entire DOM document [$document] and converts its nodes into Delta operations.
+  /// Custom blocks can be applied based on registered [customBlocks].
+  ///
+  /// Parameters:
+  /// - [$document]: The DOM document to convert into Delta operations.
+  ///
+  /// Returns:
+  /// A Delta object representing the formatted content from the DOM document.
+  ///
+  /// Example:
+  /// ```dart
+  /// final document = dparser.parse('<p>Hello <strong>world</strong></p>');
+  /// final delta = converter.convertDocument(document);
+  /// print(delta.toJson()); // Output: [{"insert":"Hello "},{"insert":"world","attributes":{"bold":true}},{"insert":"\n"}]
+  /// ```
   Delta convertDocument(dom.Document $document) {
     final Delta delta = Delta();
     final dom.Element? $body = $document.body;
@@ -98,11 +140,22 @@ class HtmlToDelta {
     return delta;
   }
 
-  /// Converts a single DOM [node] into Delta operations using [htmlToOp].
+  /// Converts a single DOM node into Delta operations using [htmlToOp].
+  ///
+  /// Processes a single DOM [node] and converts it into Delta operations using the provided [htmlToOp] instance.
+  ///
+  /// Parameters:
+  /// - [node]: The DOM node to convert into Delta operations.
+  ///
+  /// Returns:
+  /// A list of Operation objects representing the formatted content of the node.
   ///
-  /// Processes a single DOM node [node] and converts it into Delta operations
-  /// using the provided [htmlToOp] instance. Returns a list of Operation objects
-  /// representing the formatted content
+  /// Example:
+  /// ```dart
+  /// final node = dparser.parseFragment('<strong>Hello</strong>');
+  /// final operations = converter.nodeToOperation(node.firstChild!, converter.htmlToOp);
+  /// print(operations); // Output: [Operation{insert: "Hello", attributes: {bold: true}}]
+  /// ```
   List<Operation> nodeToOperation(dom.Node node, HtmlOperations htmlToOp) {
     List<Operation> operations = [];
     if (node is dom.Text) {