From 2c50a9b22d7eb9323c0f735506923fc0c606f579 Mon Sep 17 00:00:00 2001
From: CaiJingLong <cjl_spy@163.com>
Date: Wed, 11 Oct 2023 10:02:13 +0800
Subject: [PATCH] docs: Add dartdoc for classes

---
 CHANGELOG.md            |  4 ++++
 lib/mvimg.dart          | 45 ++++++++++++++++++++++++++++++++++++++---
 lib/src/mvimg_base.dart | 22 +++++++++++++++++++-
 pubspec.yaml            |  2 +-
 4 files changed, 68 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 020107d..8e4d6f5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 1.1.1
+
+- Add dartdoc for classes.
+
 ## 1.1.0
 
 - Feat: Support MP.jpg format.
diff --git a/lib/mvimg.dart b/lib/mvimg.dart
index dd476dd..ad1ef2c 100644
--- a/lib/mvimg.dart
+++ b/lib/mvimg.dart
@@ -1,7 +1,46 @@
-/// Support for doing something awesome.
+/// A library for support MVIMG or Motion Photo.
+/// It is a dart library, not a flutter plugin.
 ///
-/// More dartdocs go here.
+/// Just like this:
+/// - `MVIMG_XXXX.jpg`
+/// - `XXXX.MP.jpg`
+///
+/// Example:
+///
+/// ```dart
+///   import 'dart:io';
+///
+///   import 'package:buff/buff_io.dart';
+///   import 'package:mvimg/mvimg.dart';
+///
+///   void main() {
+///     final mvimg = Mvimg(FileBufferInput.fromPath('assets/test.jpg'));
+///     mvimg.decode();
+///     try {
+///       if (!mvimg.isMvimg()) {
+///         print('not mvimg');
+///         return;
+///       }
+///
+///       final img = mvimg.getImageBytes();
+///       final video = mvimg.getVideoBytes();
+///
+///       final videoOutputPath = 'assets/split/output.mp4';
+///       final imgOutputPath = 'assets/split/output.jpg';
+///
+///       final videoFile = File(videoOutputPath);
+///       final imgFile = File(imgOutputPath);
+///
+///       videoFile.createSync(recursive: true);
+///       imgFile.createSync(recursive: true);
+///
+///       videoFile.writeAsBytesSync(video);
+///       imgFile.writeAsBytesSync(img);
+///     } finally {
+///       mvimg.dispose();
+///     }
+///   }
+/// ```
 library mvimg;
 
 export 'src/mvimg_base.dart';
-
diff --git a/lib/src/mvimg_base.dart b/lib/src/mvimg_base.dart
index fb9b04d..82fd8b7 100644
--- a/lib/src/mvimg_base.dart
+++ b/lib/src/mvimg_base.dart
@@ -11,16 +11,27 @@ class _Range {
   _Range(this.start, this.end);
 }
 
-/// Just support jpeg + mp4
+/// A class for decoding mvimg files, which are composed of a jpeg image and an mp4 video.
+/// Support like this:
+/// - `MVIMG_XXXX.jpg`
+/// - `XXXX.MP.jpg`
 class Mvimg {
+  /// The input buffer.
+  ///
+  /// See also:
+  /// [BufferInput] of `buff` package.
   final BufferInput input;
 
+  /// Creates a [Mvimg] from a [BufferInput].
   Mvimg(this.input);
 
   bool _isMvImg = false;
 
   _Range? _videoRange;
 
+  /// Decodes the mvimg file.
+  ///
+  /// Just call this method after, the [isMvimg], [getImageBytes] or [getVideoBytes] is valid.
   void decode() {
     try {
       _readContent();
@@ -126,21 +137,30 @@ class Mvimg {
     throw Exception('Can not find video range');
   }
 
+  /// Closes the input buffer.
+  ///
+  /// Must call this method after use.
   void dispose() {
     input.close();
   }
 
+  /// Returns true if the file is a mvimg or motion photo file.
   bool isMvimg() {
     return _isMvImg;
   }
 
+  /// Returns the offset of the start of the video in the file.
   int get videoStartOffset => _videoRange?.start ?? 0;
+
+  /// Returns the offset of the end of the video in the file.
   int get videoEndOffset => _videoRange?.end ?? input.length;
 
+  /// Returns the bytes of the jpeg image in the file.
   List<int> getImageBytes() {
     return input.getBytes(0, videoStartOffset);
   }
 
+  /// Returns the bytes of the mp4 video in the file.
   List<int> getVideoBytes() {
     if (_isMvImg) {
       return input.getBytes(videoStartOffset, videoEndOffset);
diff --git a/pubspec.yaml b/pubspec.yaml
index 0835527..e580845 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,6 +1,6 @@
 name: mvimg
 description: A library to split mvimg(android motion video) file.
-version: 1.1.0
+version: 1.1.1
 repository: https://github.com/caijinglong/mvimg
 
 environment: