Update documentation and doc-tests.

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 <https://docs.rs/kamadak-exif>.
+
+   See examples directory for sample codes.
+
 Dependencies
 ------------
 

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

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;
 }

src/reader.rs

@@ -66,6 +66,7 @@ impl Reader {
     /// If an error occurred, `exif::Error` is returned.
     pub fn new<R>(reader: &mut R)
                   -> Result<Reader, Error> 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) {

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 =>

src/tiff.rs

@@ -90,7 +90,7 @@ fn parse_ifd<'a, E>(fields: &mut Vec<Field<'a>>, 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<DateTime, Error> {
         if data == b"    :  :     :  :  " || data == b"                   " {
             return Err(Error::BlankValue("DateTime is blank"));

src/value.rs

@@ -35,7 +35,7 @@ pub enum Value<'a> {
     /// Vector of 8-bit unsigned integers.
     Byte(Vec<u8>),
     /// 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.

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>>,