From 8e5b24bef2d59ee224fef5d0c939f72bd5cb1bfd Mon Sep 17 00:00:00 2001
From: lifegpc <g1710431395@gmail.com>
Date: Fri, 13 May 2022 21:00:29 +0800
Subject: [PATCH] Update the document

---
 src/avdict.rs | 19 +++++++++++++++++++
 src/exif.rs   | 15 +++++++++++++++
 src/main.rs   |  2 ++
 3 files changed, 36 insertions(+)

diff --git a/src/avdict.rs b/src/avdict.rs
index 0d80c1d..19267bc 100644
--- a/src/avdict.rs
+++ b/src/avdict.rs
@@ -17,11 +17,16 @@ use std::os::raw::c_char;
 use std::os::raw::c_int;
 use std::str::Utf8Error;
 
+/// Error when operate AVDictionary
 #[derive(Debug, derive_more::From, PartialEq)]
 pub enum AVDictError {
+    /// The normal error message
     String(String),
+    /// Failed to use UTF-8 to decode string
     Utf8Error(Utf8Error),
+    /// The error code from ffmpeg
     CodeError(AVDictCodeError),
+    /// The error occured when convert data to the string in C.
     ToCstr(ToCStrError)
 }
 
@@ -48,12 +53,15 @@ impl Display for AVDictError {
     }
 }
 
+/// The error returned from the ffmpeg
 #[derive(Clone, Copy, Debug, PartialEq, PartialOrd)]
 pub struct AVDictCodeError {
+    /// Error code
     err: c_int,
 }
 
 impl AVDictCodeError {
+    /// Convert error code to error message
     pub fn to_str(&self) -> Result<String, AVDictError> {
         let s = unsafe { _avdict::avdict_get_errmsg(self.err) };
         if s.is_null() {
@@ -89,6 +97,7 @@ impl From<c_int> for AVDictCodeError {
 }
 
 flagset::flags! {
+    /// The flags of Dictionary
     pub enum AVDictFlags: c_int {
         /// Only get an entry with exact-case key match.
         MatchCase = _avdict::AV_DICT_MATCH_CASE as c_int,
@@ -108,18 +117,22 @@ flagset::flags! {
     }
 }
 
+/// An instance of the AVDictionary
 pub struct AVDict {
     pub m: *mut _avdict::AVDict,
 }
 
 #[allow(dead_code)]
 impl AVDict {
+    /// Create a new instance of the AVDictionary
     pub fn new() -> Self {
         Self {
             m: 0 as *mut _avdict::AVDict,
         }
     }
 
+    /// Clone a new instance from current [AVDict].
+    /// * `flags` - The flags to use when setting entries
     pub fn copy<T: ToFlagSet<AVDictFlags>>(&self, flags: T) -> Result<Self, AVDictError> {
         if self.m.is_null() {
             return Ok(Self::new());
@@ -135,6 +148,9 @@ impl AVDict {
         })
     }
 
+    /// Set all entries in the map to the dictionary
+    /// * `maps` - The map which contains entries
+    /// * `flags` - The flags to use when setting entries.
     pub fn from_map<K: ToCStr, V: ToCStr, F: ToFlagSet<AVDictFlags>>(&mut self, maps: &HashMap<K, V>, flags: F) -> Result<(), AVDictError> {
         let flags = flags.to_flag_set();
         for (k, v) in maps {
@@ -143,6 +159,9 @@ impl AVDict {
         Ok(())
     }
 
+    /// Get a dictionary value with matching key.
+    /// * `key` - The matching key
+    /// * `flags` - The flags to control how entry is retrieved.
     pub fn get<K: ToCStr, F: ToFlagSet<AVDictFlags>>(&self, key: K, flags: F) -> Result<Option<CString>, AVDictError> {
         if self.m.is_null() {
             return Ok(None);
diff --git a/src/exif.rs b/src/exif.rs
index c20cc65..491d7fa 100644
--- a/src/exif.rs
+++ b/src/exif.rs
@@ -582,6 +582,7 @@ impl ExifDataRef {
         }
         Some(r as usize)
     }
+
     /// Return true if there is no Exif metadata.
     pub fn empty(&self) -> Option<bool> {
         let data = unsafe { self.to_raw_handle() };
@@ -623,12 +624,15 @@ impl ToRawHandle<ExifDataRef> for ExifDataRef {
     }
 }
 
+/// An image
 pub struct ExifImage {
     img: *mut _exif::ExifImage,
 }
 
 #[allow(dead_code)]
 impl ExifImage {
+    /// Create a new image instance
+    /// * `file_name` - File name
     pub fn new<S: AsRef<OsStr> + ?Sized>(file_name: &S) -> Result<Self, ()> {
         let p = Path::new(file_name);
         if !p.exists() {
@@ -651,6 +655,8 @@ impl ExifImage {
         Ok(Self { img: f })
     }
 
+    /// Returns a read only [ExifData] ([ExifDataRef]) instance containing currently buffered Exif data.
+    /// The Exif data in the returned instance will be written to the image when [Self::write_metadata()] is called.
     pub fn exif_data(&self) -> Option<&ExifDataRef> {
         if self.img.is_null() {
             return None;
@@ -662,6 +668,9 @@ impl ExifImage {
         unsafe { Some(ExifDataRef::from_const_handle(d)) }
     }
 
+    /// Assign new Exif data.
+    /// The new Exif data is not written to the image until the [Self::write_metadata()] method is called.
+    /// * `data` - An [ExifData] instance holding Exif data to be copied
     pub fn set_exif_data(&mut self, data: &ExifData) -> Result<(), ()> {
         if self.img.is_null() {
             return Err(());
@@ -678,6 +687,11 @@ impl ExifImage {
         }
     }
 
+    /// Write metadata back to the image.
+    /// 
+    /// All existing metadata sections in the image are either created, replaced, or erased.
+    /// If values for a given metadata type have been assigned, a section for that metadata type will either be created or replaced.
+    /// If no values have been assigned to a given metadata type, any exists section for that metadata type will be removed from the image.
     pub fn write_metadata(&mut self) -> Result<(), ()> {
         if self.img.is_null() {
             return Err(());
@@ -695,6 +709,7 @@ impl Drop for ExifImage {
     fn drop(&mut self) {
         if !self.img.is_null() {
             unsafe { _exif::free_exif_image(self.img) };
+            self.img = 0 as *mut _exif::ExifImage;
         }
     }
 }
diff --git a/src/main.rs b/src/main.rs
index b2890ef..76804a6 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -31,12 +31,14 @@ mod _exif;
 mod _ugoira;
 mod author_name_filter;
 #[cfg(feature = "avdict")]
+/// A rust wrapper for [FFMPEG](https://ffmpeg.org/)'s [AVDictionary](https://ffmpeg.org/doxygen/trunk/group__lavu__dict.html)
 mod avdict;
 mod cookies;
 mod data;
 mod download;
 mod dur;
 #[cfg(feature = "exif")]
+/// Used to read/modify image's exif data
 mod exif;
 /// Used to extend some thirdparty library
 mod ext;