Merge pull request #95 from fluttercandies/add-doc

doc: Add api document for dart classes

example/lib/draw_example_page.dart

@@ -190,8 +190,8 @@ class _DrawExamplePageState extends State<DrawExamplePage> {
           paint: paint,
         );
         path.move(Offset.zero);
-        path.lineTo(randomOffset(), paint);
-        path.lineTo(randomOffset(), paint);
+        path.lineTo(randomOffset());
+        path.lineTo(randomOffset());
         path.bezier2To(randomOffset(), randomOffset());
         path.bezier3To(randomOffset(), randomOffset(), randomOffset());
         await addDrawPart(path);

lib/src/channel.dart

@@ -5,18 +5,22 @@ import 'package:flutter/services.dart';
 
 import 'option/edit_options.dart';
 
+/// Wrapper for [MethodChannel].
 class NativeChannel {
   const NativeChannel._();
 
+  /// The channel for use native method.
   static const MethodChannel channel = MethodChannel(
     'com.fluttercandies/image_editor',
   );
 
+  /// Get the cache directory path.
   static Future<Directory> getCachePath() async {
     final path = await channel.invokeMethod('getCachePath');
     return Directory(path);
   }
 
+  /// Handle memory source and get file result.
   static Future<String> memoryToFile(
     Uint8List memory,
     ImageEditorOption option,
@@ -33,6 +37,7 @@ class NativeChannel {
     });
   }
 
+  /// Handle memory source and get momory result.
   static Future<Uint8List> memoryToMemory(
     Uint8List memory,
     ImageEditorOption option,
@@ -49,6 +54,7 @@ class NativeChannel {
     return result;
   }
 
+  /// Handle file source and get momory result.
   static Future<Uint8List> fileToMemory(
     String path,
     ImageEditorOption option,
@@ -64,6 +70,7 @@ class NativeChannel {
     });
   }
 
+  /// Handle file source and get file result.
   static Future<String> fileToFile(
     String src,
     ImageEditorOption option,

lib/src/convert_value.dart

@@ -1,3 +1,8 @@
+import 'package:flutter/services.dart';
+
+/// Used to describe fields that can be JSON,
+/// mainly used for [MethodChannel] invoke.
 mixin JsonAble {
+  /// Convert current instance to [Map].
   Map<String, Object?> toJson();
 }

lib/src/editor.dart

@@ -6,11 +6,17 @@ import 'channel.dart';
 import 'image_handler.dart';
 import 'option/edit_options.dart';
 
+/// The main class of ImageEditor plugin.
 class ImageEditor {
   const ImageEditor._();
 
-  /// [image] Uint8List
-  /// [imageEditorOption] option of
+  /// The [image] is a source of image.
+  ///
+  /// The [imageEditorOption] option for edit image.
+  ///
+  /// The method will return a [Uint8List] as image result.
+  ///
+  /// If result is null, it means handle image error.
   static Future<Uint8List?> editImage({
     required Uint8List image,
     required ImageEditorOption imageEditorOption,
@@ -31,6 +37,13 @@ class ImageEditor {
     return tmp;
   }
 
+  /// The [file] is the source of image.
+  ///
+  /// The [imageEditorOption] is the option for edit image.
+  ///
+  /// The method will return a [Uint8List] as image result.
+  ///
+  /// If result is null, it means handle image error.
   static Future<Uint8List?> editFileImage({
     required File file,
     required ImageEditorOption imageEditorOption,
@@ -57,6 +70,13 @@ class ImageEditor {
     }
   }
 
+  /// The [file] is the source of image.
+  ///
+  /// The [imageEditorOption] is the option for edit image.
+  ///
+  /// The method will return a [File] as image result.
+  ///
+  /// If result is null, it means handle image error.
   static Future<File?> editFileImageAndGetFile({
     required File file,
     required ImageEditorOption imageEditorOption,
@@ -78,6 +98,13 @@ class ImageEditor {
     return tmp;
   }
 
+  /// The [image] is the source of image.
+  ///
+  /// The [imageEditorOption] is the option for edit image.
+  ///
+  /// The method will return a [File] as image result.
+  ///
+  /// If result is null, it means handle image error.
   static Future<File> editImageAndGetFile({
     required Uint8List image,
     required ImageEditorOption imageEditorOption,
@@ -102,6 +129,7 @@ class ImageEditor {
     return file;
   }
 
+  /// The method will create a temp file path.
   static Future<String> _createTmpFilePath() async {
     final cacheDir = await NativeChannel.getCachePath();
     final name = DateTime.now().millisecondsSinceEpoch;

lib/src/error.dart

@@ -1,6 +1,9 @@
+/// Error for handle image.
 class HandleError implements Exception {
+  /// Error for handle image.
   HandleError([this.msg = '']);
 
+  /// The message of error.
   final String msg;
 
   @override

lib/src/font_manager.dart

@@ -2,6 +2,7 @@ import 'dart:io';
 
 import 'channel.dart';
 
+/// Wrapper for use channel to register font for add text.
 class FontManager {
   const FontManager._();
 

lib/src/image_handler.dart

@@ -6,6 +6,7 @@ import 'error.dart';
 import 'option/edit_options.dart';
 import 'type.dart';
 
+/// Wrapper for use channel to handle image.
 class ImageHandler {
   ImageHandler.memory(this._memory)
       : _type = SrcType.memory,

lib/src/image_source.dart

@@ -3,39 +3,50 @@ import 'dart:typed_data';
 
 import 'convert_value.dart';
 
+/// Used to describe the source of an image.
 abstract class ImageSource with JsonAble {
+  /// Used to describe the source of an image.
   const ImageSource();
 
+  /// Used to describe the memory image.
   factory ImageSource.memory(Uint8List uint8list) {
     return MemoryImageSource(uint8list);
   }
 
+  /// Used to describe the file image.
   factory ImageSource.file(File file) {
     return FileImageSource(file);
   }
 
+  /// Used to describe the file image.
   factory ImageSource.path(String path) {
     return FileImageSource.path(path);
   }
 
+  /// The image data as [Uint8List].
   Uint8List get memory;
 
   @override
   Map<String, Object?> toJson() => <String, Object?>{'memory': memory};
 }
 
+/// The memory image source.
 class MemoryImageSource extends ImageSource {
   const MemoryImageSource(Uint8List uint8list) : memory = uint8list;
 
   @override
   final Uint8List memory;
 }
 
+/// The file image source.
 class FileImageSource extends ImageSource {
+  /// Use [file] to create image source.
   const FileImageSource(this.file);
 
+  /// Use [path] to create image source.
   FileImageSource.path(String path) : file = File(path);
 
+  /// The file of image.
   final File file;
 
   @override

lib/src/merge/image_merger.dart

@@ -5,15 +5,18 @@ import 'package:image_editor/src/channel.dart';
 
 import 'merge_option.dart';
 
+/// Use the class to merge multiple images.
 class ImageMerger {
   const ImageMerger._();
 
+  /// Merge multiple images.
   static Future<Uint8List?> mergeToMemory({required ImageMergeOption option}) {
     return NativeChannel.channel.invokeMethod('mergeToMemory', {
       'option': option.toJson(),
     });
   }
 
+  /// Merge multiple images and get file.
   static Future<File?> mergeToFile({required ImageMergeOption option}) {
     return NativeChannel.channel.invokeMethod('mergeToFile', {
       'option': option.toJson(),

lib/src/merge/merge_option.dart

@@ -5,17 +5,23 @@ import '../image_source.dart';
 import '../output_format.dart';
 import '../position.dart';
 
+/// Merge multiple images option.
 class ImageMergeOption with JsonAble {
   ImageMergeOption({
     required this.canvasSize,
     this.format = const OutputFormat.jpeg(90),
   }) : assert(canvasSize > Size.zero);
 
+  /// The canvas size. (output image size)
   final Size canvasSize;
+
+  /// Output format for result image.
   final OutputFormat format;
 
+  /// All merge image options.
   final List<MergeImageConfig> _mergeImageConfig = <MergeImageConfig>[];
 
+  /// Add a merge image option.
   void addImage(MergeImageConfig config) {
     _mergeImageConfig.add(config);
   }
@@ -31,13 +37,18 @@ class ImageMergeOption with JsonAble {
   }
 }
 
+/// Merge image option.
 class MergeImageConfig with JsonAble {
+  /// Merge image option.
   const MergeImageConfig({
     required this.image,
     required this.position,
   });
 
+  /// The image source.
   final ImageSource image;
+
+  /// The position of image.
   final ImagePosition position;
 
   @override

lib/src/option/add_text.dart

@@ -1,10 +1,13 @@
 part of 'edit_options.dart';
 
+/// Add text to image.
 class AddTextOption implements Option {
   AddTextOption();
 
+  /// The items of added texts.
   final List<EditorText> texts = <EditorText>[];
 
+  /// Add [text] to [texts].
   void addText(EditorText text) {
     texts.add(text);
   }
@@ -23,6 +26,7 @@ class AddTextOption implements Option {
   }
 }
 
+/// Descript of a text.
 class EditorText {
   const EditorText({
     required this.text,
@@ -32,10 +36,19 @@ class EditorText {
     this.fontName = '',
   });
 
+  /// The text.
   final String text;
+
+  /// The offset of text.
   final Offset offset;
+
+  /// The font size of text.
   final int fontSizePx;
+
+  /// The color of text.
   final Color textColor;
+
+  /// The font name of text, if fontName is empty string, the text will use system font.
   final String fontName;
 
   int get y {

lib/src/option/clip.dart

@@ -1,14 +1,22 @@
 part of 'edit_options.dart';
 
+///
+/// {@template image_editor.option.clip}
+///
+/// The clip option is used to clip image.
+///
+/// {@endtemplate}
 class ClipOption implements Option {
-  ClipOption({
+  /// {@macro image_editor.option.clip}
+  const ClipOption({
     this.x = 0,
     this.y = 0,
     required this.width,
     required this.height,
   })  : assert(width > 0 && height > 0),
         assert(x >= 0, y >= 0);
 
+  /// {@macro image_editor.option.clip}
   factory ClipOption.fromRect(Rect rect) {
     return ClipOption(
       x: rect.left.round(),
@@ -18,6 +26,7 @@ class ClipOption implements Option {
     );
   }
 
+  /// {@macro image_editor.option.clip}
   factory ClipOption.fromOffset(Offset start, Offset end) {
     return ClipOption(
       x: start.dx.round(),
@@ -27,9 +36,20 @@ class ClipOption implements Option {
     );
   }
 
+  /// The x coordinate of clip.
   final num x;
+
+  /// The y coordinate of clip.
   final num y;
+
+  /// The width of clip.
+  ///
+  /// The width must be greater than 0.
   final num width;
+
+  /// The height of clip.
+  ///
+  /// The height must be greater than 0.
   final num height;
 
   @override