From d882dce9a0822c2d5dbc6ddf26d10b10b36a47a3 Mon Sep 17 00:00:00 2001 From: KAMADA Ken'ichi Date: Sat, 13 Jan 2018 23:33:45 +0900 Subject: [PATCH] Update documentation and doc-tests. --- README | 5 +++++ src/error.rs | 2 +- src/lib.rs | 5 +++-- src/reader.rs | 1 + src/tag.rs | 17 +++++++++++++++-- src/tiff.rs | 4 +++- src/value.rs | 2 +- src/writer.rs | 22 ++++++++++++++++++++++ 8 files changed, 51 insertions(+), 7 deletions(-) diff --git a/README b/README index 28958ee..c075f3b 100644 --- a/README +++ b/README @@ -19,6 +19,11 @@ Usage extern crate exif; + Run "cargo doc" in the source directory to generate the API reference. + It is also available online at . + + See examples directory for sample codes. + Dependencies ------------ diff --git a/src/error.rs b/src/error.rs index 92839a9..5c1654d 100644 --- a/src/error.rs +++ b/src/error.rs @@ -36,7 +36,7 @@ pub enum Error { /// Input data could not be read due to an I/O error and /// a `std::io::Error` value is associated with this variant. Io(io::Error), - /// Exif attribute information was not found. + /// Exif attribute information was not found in JPEG data. NotFound(&'static str), /// The value of the field is blank. Some fields have blank values /// whose meanings are defined as "unknown". Such a blank value diff --git a/src/lib.rs b/src/lib.rs index 9ec03f6..8a4fced 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -38,7 +38,8 @@ //! let reader = exif::Reader::new( //! &mut std::io::BufReader::new(&file)).unwrap(); //! for f in reader.fields() { -//! println!("{} {} {:?}", f.tag, f.thumbnail, f.value); +//! println!("{} {} {}", +//! f.tag, f.thumbnail, f.value.display_as(f.tag)); //! } //! } //! ``` @@ -63,7 +64,7 @@ pub use tiff::parse_exif; pub use value::Value; pub use value::{Rational, SRational}; -/// The interfaces in this module is experimental and unstable. +/// The interfaces in this module are experimental and unstable. pub mod experimental { pub use writer::Writer; } diff --git a/src/reader.rs b/src/reader.rs index af399e8..004584e 100644 --- a/src/reader.rs +++ b/src/reader.rs @@ -66,6 +66,7 @@ impl Reader { /// If an error occurred, `exif::Error` is returned. pub fn new(reader: &mut R) -> Result where R: io::BufRead { + // Parse the data. let mut buf = Vec::new(); try!(reader.by_ref().take(4).read_to_end(&mut buf)); if jpeg::is_jpeg(&buf) { diff --git a/src/tag.rs b/src/tag.rs index 11fcf99..455e3bb 100644 --- a/src/tag.rs +++ b/src/tag.rs @@ -56,12 +56,25 @@ pub struct Tag(pub Context, pub u16); impl Tag { /// Returns the context of the tag. + /// + /// # Examples + /// ``` + /// use exif::{Context, Tag}; + /// assert_eq!(Tag::DateTime.context(), Context::Tiff); + /// assert_eq!(Tag::ExposureTime.context(), Context::Exif); + /// ``` #[inline] pub fn context(self) -> Context { self.0 } /// Returns the tag number. + /// + /// # Examples + /// ``` + /// use exif::Tag; + /// assert_eq!(Tag::DateTime.number(), 0x132); + /// ``` #[inline] pub fn number(self) -> u16 { self.1 @@ -1040,8 +1053,8 @@ fn d_gpslatlongref(w: &mut fmt::Write, value: &Value) -> fmt::Result { } } -// GPSLatitude (Exif/GPS 0x2), GPSLongitude (Exif 0x4), -// GPSDestLatitude (Exif/GPS 0x14), GPSDestLongitude (Exif 0x16) +// GPSLatitude (Exif/GPS 0x2), GPSLongitude (Exif/GPS 0x4), +// GPSDestLatitude (Exif/GPS 0x14), GPSDestLongitude (Exif/GPS 0x16) fn d_gpsdms(w: &mut fmt::Write, value: &Value) -> fmt::Result { match *value { Value::Rational(ref v) if v.len() >= 3 => diff --git a/src/tiff.rs b/src/tiff.rs index af6f827..cd66553 100644 --- a/src/tiff.rs +++ b/src/tiff.rs @@ -90,7 +90,7 @@ fn parse_ifd<'a, E>(fields: &mut Vec>, data: &'a [u8], } let count = E::loadu16(data, offset) as usize; - // Array of entries. (count * 12) never overflow. + // Array of entries. (count * 12) never overflows. if data.len() - offset - 2 < count * 12 { return Err(Error::InvalidFormat("Truncated IFD")); } @@ -186,6 +186,8 @@ pub struct DateTime { impl DateTime { /// Parse an ASCII data of a DateTime field. The range of a number /// is not validated, so, for example, 13 may be returned as the month. + /// + /// If the value is blank, `Error::BlankValue` is returned. pub fn from_ascii(data: &[u8]) -> Result { if data == b" : : : : " || data == b" " { return Err(Error::BlankValue("DateTime is blank")); diff --git a/src/value.rs b/src/value.rs index 73888e1..85ead07 100644 --- a/src/value.rs +++ b/src/value.rs @@ -35,7 +35,7 @@ pub enum Value<'a> { /// Vector of 8-bit unsigned integers. Byte(Vec), /// Vector of slices of 8-bit bytes containing 7-bit ASCII characters. - /// The trailing null character is not included. Note that + /// The trailing null characters are not included. Note that /// the 8th bits may present if a non-conforming data is given. Ascii(Vec<&'a [u8]>), /// Vector of 16-bit unsigned integers. diff --git a/src/writer.rs b/src/writer.rs index 41710e1..9468ab3 100644 --- a/src/writer.rs +++ b/src/writer.rs @@ -36,6 +36,28 @@ use tiff::{Field, TIFF_BE_SIG, TIFF_LE_SIG}; use value::Value; /// The `Writer` struct is used to encode and write Exif data. +/// +/// # Examples +/// +/// ``` +/// use exif::{Field, Value, Tag}; +/// use exif::experimental::Writer; +/// let image_desc = Field { +/// tag: Tag::ImageDescription, +/// thumbnail: false, +/// value: Value::Ascii(vec![b"Sample"]), +/// }; +/// let mut writer = Writer::new(); +/// let mut buf = std::io::Cursor::new(Vec::new()); +/// writer.push_field(&image_desc); +/// writer.write(&mut buf, false).unwrap(); +/// static expected: &[u8] = +/// b"\x4d\x4d\x00\x2a\x00\x00\x00\x08\ +/// \x00\x01\x01\x0e\x00\x02\x00\x00\x00\x07\x00\x00\x00\x1a\ +/// \x00\x00\x00\x00\ +/// Sample\0"; +/// assert_eq!(buf.into_inner(), expected); +/// ``` #[derive(Debug)] pub struct Writer<'a> { tiff_fields: Vec<&'a Field<'a>>,