From 88cb7331cfb284cfd0279bb804da560626782a3d Mon Sep 17 00:00:00 2001
From: Dustin Oprea <myselfasunder@gmail.com>
Date: Tue, 1 May 2018 10:57:55 -0400
Subject: [PATCH] documentation: Added examples.

- Renamed DefaultEncodeByteOrder to EncodeDefaultByteOrder.
---
 exif.go                    |  4 +--
 exif_test.go               | 15 ++++++++++
 ifd_builder_encode.go      |  2 +-
 ifd_builder_encode_test.go | 61 ++++++++++++++++++++++++++++++++++++++
 ifd_enumerate.go           |  8 +++--
 5 files changed, 84 insertions(+), 6 deletions(-)

diff --git a/exif.go b/exif.go
index 95ba94c..a204163 100644
--- a/exif.go
+++ b/exif.go
@@ -36,8 +36,8 @@ var (
 
     ExifHeaderPrefixBytes = []byte("Exif\000\000")
 
-    // DefaultEncodeByteOrder is the default byte-order for encoding operations.
-    DefaultEncodeByteOrder = binary.BigEndian
+    // EncodeDefaultByteOrder is the default byte-order for encoding operations.
+    EncodeDefaultByteOrder = binary.BigEndian
 )
 
 var (
diff --git a/exif_test.go b/exif_test.go
index 58076b9..4b230a6 100644
--- a/exif_test.go
+++ b/exif_test.go
@@ -333,6 +333,21 @@ func TestBuildAndParseExifHeader(t *testing.T) {
     } else if eh.FirstIfdOffset != 0x11223344 {
         t.Fatalf("First IFD offset not correct.")
     }
+
+    fmt.Printf("%v\n", eh)
+}
+
+func ExampleBuildExifHeader() {
+    headerBytes, err := BuildExifHeader(EncodeDefaultByteOrder, 0x11223344)
+    log.PanicIf(err)
+
+    e := NewExif()
+
+    eh, err := e.ParseExifHeader(headerBytes)
+    log.PanicIf(err)
+
+    fmt.Printf("%v\n", eh)
+    // Output: ExifHeader<BYTE-ORDER=[BigEndian] FIRST-IFD-OFFSET=(0x11223344)>
 }
 
 func init() {
diff --git a/ifd_builder_encode.go b/ifd_builder_encode.go
index e8dec5d..f048469 100644
--- a/ifd_builder_encode.go
+++ b/ifd_builder_encode.go
@@ -407,7 +407,7 @@ func (ibe *IfdByteEncoder) EncodeToExif(ib *IfdBuilder) (data []byte, err error)
 
     b := new(bytes.Buffer)
 
-    headerBytes, err := BuildExifHeader(DefaultEncodeByteOrder, ExifDefaultFirstIfdOffset)
+    headerBytes, err := BuildExifHeader(EncodeDefaultByteOrder, ExifDefaultFirstIfdOffset)
     log.PanicIf(err)
 
     _, err = b.Write(headerBytes)
diff --git a/ifd_builder_encode_test.go b/ifd_builder_encode_test.go
index 4d250ea..27d6ba8 100644
--- a/ifd_builder_encode_test.go
+++ b/ifd_builder_encode_test.go
@@ -4,6 +4,7 @@ import (
     "testing"
     "bytes"
     "reflect"
+    "fmt"
 
     "github.com/dsoprea/go-logging"
 )
@@ -742,6 +743,66 @@ func Test_IfdByteEncoder_EncodeToExif(t *testing.T) {
     validateExifSimpleTestIb(exifData, t)
 }
 
+func ExampleIfdByteEncoder_EncodeToExif() {
+    // Construct an IFD.
+
+    ib := NewIfdBuilder(RootIi, EncodeDefaultByteOrder)
+
+    err := ib.AddFromConfig(0x000b, "asciivalue")
+    log.PanicIf(err)
+
+    err = ib.AddFromConfig(0x0150, []uint8 { 0x11 })
+    log.PanicIf(err)
+
+    err = ib.AddFromConfig(0x00ff, []uint16 { 0x2233 })
+    log.PanicIf(err)
+
+    err = ib.AddFromConfig(0x0100, []uint32 { 0x44556677 })
+    log.PanicIf(err)
+
+    err = ib.AddFromConfig(0x013e, []Rational { { Numerator: 0x11112222, Denominator: 0x33334444 } })
+    log.PanicIf(err)
+
+    err = ib.AddFromConfig(0x9201, []SignedRational { { Numerator: 0x11112222, Denominator: 0x33334444 } })
+    log.PanicIf(err)
+
+
+    // Encode it.
+
+    ibe := NewIfdByteEncoder()
+
+    exifData, err := ibe.EncodeToExif(ib)
+    log.PanicIf(err)
+
+
+    // Parse it so we can see it.
+
+    e := NewExif()
+
+    _, index, err := e.Collect(exifData)
+    log.PanicIf(err)
+
+    // addressableData is the byte-slice where the allocated data can be
+    // resolved (where position 0x0 will correlate with offset 0x0).
+    addressableData := exifData[ExifAddressableAreaStart:]
+
+    for i, e := range index.RootIfd.Entries {
+        value, err := e.Value(EncodeDefaultByteOrder, addressableData)
+        log.PanicIf(err)
+
+        fmt.Printf("%d: %s %v\n", i, e, value)
+    }
+
+    // Output:
+    //
+    // 0: IfdTagEntry<TAG-IFD=[] TAG-ID=(0x0b) TAG-TYPE=[ASCII] UNIT-COUNT=(11)> asciivalue
+    // 1: IfdTagEntry<TAG-IFD=[] TAG-ID=(0x150) TAG-TYPE=[BYTE] UNIT-COUNT=(1)> [17]
+    // 2: IfdTagEntry<TAG-IFD=[] TAG-ID=(0xff) TAG-TYPE=[SHORT] UNIT-COUNT=(1)> [8755]
+    // 3: IfdTagEntry<TAG-IFD=[] TAG-ID=(0x100) TAG-TYPE=[LONG] UNIT-COUNT=(1)> [1146447479]
+    // 4: IfdTagEntry<TAG-IFD=[] TAG-ID=(0x13e) TAG-TYPE=[RATIONAL] UNIT-COUNT=(1)> [{286335522 858997828}]
+    // 5: IfdTagEntry<TAG-IFD=[] TAG-ID=(0x9201) TAG-TYPE=[SRATIONAL] UNIT-COUNT=(1)> [{286335522 858997828}]
+}
+
 // TODO(dustin): !! Write test with both chained and child IFDs
 
 // TODO(dustin): !! Test all types.
diff --git a/ifd_enumerate.go b/ifd_enumerate.go
index 0052b9f..7112c18 100644
--- a/ifd_enumerate.go
+++ b/ifd_enumerate.go
@@ -16,9 +16,11 @@ var (
 
 
 // IfdTagEnumerator knows how to decode an IFD and all of the tags it
-// describes. Note that the IFDs and the actual values floating throughout the
-// whole EXIF block, but the IFD itself has just a minor header and a set of
-// repeating, statically-sized records. So, the tags (though not their values)
+// describes.
+//
+// The IFDs and the actual values can float throughout the EXIF block, but the
+// IFD itself is just a minor header followed by a set of repeating,
+// statically-sized records. So, the tags (though notnecessarily their values)
 // are fairly simple to enumerate.
 type IfdTagEnumerator struct {
     byteOrder binary.ByteOrder