From 01fd433fb46e3a4f349db2fc6392e43c0f7865d0 Mon Sep 17 00:00:00 2001
From: Simon L <slarcher86@gmail.com>
Date: Wed, 20 May 2015 13:43:08 +0200
Subject: [PATCH] Added comments and links to ogg spec. Clarified code with
 const

---
 ogg.go | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/ogg.go b/ogg.go
index e031425..328b3ad 100644
--- a/ogg.go
+++ b/ogg.go
@@ -10,8 +10,14 @@ import (
 	"os"
 )
 
+const (
+	idType      int = 1
+	commentType     = 3
+)
+
 // ReadOGGTags reads OGG metadata from the io.ReadSeeker, returning the resulting
 // metadata in a Metadata implementation, or non-nil error if there was a problem.
+// See http://www.xiph.org/vorbis/doc/Vorbis_I_spec.html and http://www.xiph.org/ogg/doc/framing.html for details
 // TODO: Needs a more generic return type than "metadataFLAC" and the "FLAC" format is not as obvious as "Vorbis comment"
 func ReadOGGTags(r io.ReadSeeker) (Metadata, error) {
 	_, err := r.Seek(0, os.SEEK_SET)
@@ -27,6 +33,8 @@ func ReadOGGTags(r io.ReadSeeker) (Metadata, error) {
 		return nil, errors.New("expected 'OggS'")
 	}
 
+	// Skip 22 bytes of Page header to read page_segments length byte at position 26
+	// See http://www.xiph.org/ogg/doc/framing.html
 	_, err = r.Seek(22, os.SEEK_CUR)
 	if err != nil {
 		return nil, err
@@ -37,24 +45,30 @@ func ReadOGGTags(r io.ReadSeeker) (Metadata, error) {
 		return nil, err
 	}
 
+	// Seek and discard the segments
 	_, err = r.Seek(int64(nS), os.SEEK_CUR)
 	if err != nil {
 		return nil, err
 	}
 
-	idComment, err := readInt(r, 1)
+	// First packet type is identification, type 1
+	t, err := readInt(r, 1)
 	if err != nil {
 		return nil, err
 	}
-	if idComment != 1 {
+	if t != idType {
 		return nil, errors.New("expected 'vorbis' identification type 1")
 	}
 
+	// Seek and discard 29 bytes from common and identification header
+	// See http://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-610004.2
 	_, err = r.Seek(29, os.SEEK_CUR)
 	if err != nil {
 		return nil, err
 	}
 
+	// Beginning of a new page. Comment packet is on a separate page
+	// See http://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-132000A.2
 	oggs, err = readString(r, 4)
 	if err != nil {
 		return nil, err
@@ -63,6 +77,7 @@ func ReadOGGTags(r io.ReadSeeker) (Metadata, error) {
 		return nil, errors.New("expected 'OggS'")
 	}
 
+	// Skip page 2 header, same as line 30
 	_, err = r.Seek(22, os.SEEK_CUR)
 	if err != nil {
 		return nil, err
@@ -78,14 +93,16 @@ func ReadOGGTags(r io.ReadSeeker) (Metadata, error) {
 		return nil, err
 	}
 
-	typeComment, err := readInt(r, 1)
+	// Packet type is comment, type 3
+	t, err = readInt(r, 1)
 	if err != nil {
 		return nil, err
 	}
-	if typeComment != 3 {
+	if t != commentType {
 		return nil, errors.New("expected 'vorbis' comment type 3")
 	}
 
+	// Seek and discard 6 bytes from common header
 	_, err = r.Seek(6, os.SEEK_CUR)
 	if err != nil {
 		return nil, err