Added docstring as widely as possible

lib.go

@@ -7,28 +7,34 @@ import (
 	"xml"
 )
 
+// XLSXReaderError is the standard error type for otherwise undefined
+// errors in the XSLX reading process.
 type XLSXReaderError struct {
 	Error string
 }
 
+// String() returns a string value from an XLSXReaderError struct in
+// order that it might comply with the os.Error interface.
 func (e *XLSXReaderError) String() string {
 	return e.Error
 }
 
+// Sheet is a high level structure intended to provide user access to
+// the contents of a particular sheet within an XLSX file.
 type Sheet struct {
 
 }
 
+// File is a high level structure providing a slice of Sheet structs
+// to the user.
 type File struct {
 	Sheets []*Sheet
 }
 
-type FileInterface interface {
-	GetSheet(sheetname string) Sheet
-}
-
-
 
+// readSheetsFromZipFile is an internal helper function that loops
+// over the Worksheets defined in the XSLXWorkbook and loads them into
+// Sheet objects stored in the Sheets slice of a xlsx.File struct.
 func readSheetsFromZipFile(f *zip.File) ([]*Sheet, os.Error) {
 	var workbook *XLSXWorkbook
 	var error os.Error
@@ -50,6 +56,8 @@ func readSheetsFromZipFile(f *zip.File) ([]*Sheet, os.Error) {
 	return sheets, nil
 }
 
+// OpenFile() take the name of an XLSX file and returns a populated
+// xlsx.File struct for it.
 func OpenFile(filename string) (x *File, e os.Error) {
 	var f *zip.ReadCloser
 	var error os.Error
@@ -73,7 +81,6 @@ func OpenFile(filename string) (x *File, e os.Error) {
 			}
 			xlsxFile.Sheets = sheets
 		}
-
 	}
 	f.Close()
 	return xlsxFile, nil

lib_test.go

@@ -8,6 +8,8 @@ import (
 )
 
 
+// Test we can correctly open a XSLX file and return a xlsx.File
+// struct.
 func TestOpenFile(t *testing.T) {
 	var xlsxFile *File
 	var error os.Error
@@ -23,18 +25,9 @@ func TestOpenFile(t *testing.T) {
 
 }
 
-func TestExtractSheets(t *testing.T) {
-	var xlsxFile *File
-	var sheets []*Sheet
-	xlsxFile, _ = OpenFile("testfile.xlsx")
-	sheets = xlsxFile.Sheets
-	if len(sheets) == 0 {
-		t.Error("No sheets read from XLSX file")
-		return
-	}
-	fmt.Printf("%v\n", len(sheets))
-}
-
+// Test that when we open a real XLSX file we create xlsx.Sheet
+// objects for the sheets inside the file and that these sheets are
+// themselves correct.
 func TestCreateSheet(t *testing.T) {
 	var xlsxFile *File
 	var error os.Error

sharedstrings.go

@@ -1,6 +1,9 @@
 package xlsx
 
 
+// XLSXSST directly maps the sst element from the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main currently
+// I have not checked this for completeness - it does as much as need.
 type XLSXSST struct {
 	Count       string "attr"
 	UniqueCount string "attr"
@@ -8,16 +11,27 @@ type XLSXSST struct {
 }
 
 
+// XLSXSI directly maps the si element from the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main -
+// currently I have not checked this for completeness - it does as
+// much as I need.
 type XLSXSI struct {
 	T XLSXT
 }
 
-
+// XLSXT directly maps the t element from the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main -
+// currently I have not checked this for completeness - it does as
+// much as I need.
 type XLSXT struct {
 	Data string "chardata"
 }
 
 
+// MakeSharedStringRefTable() takes an XLSXSST struct and converts
+// it's contents to an slice of strings used to refer to string values
+// by numeric index - this is the model used within XLSX worksheet (a
+// numeric reference is stored to a shared cell value).
 func MakeSharedStringRefTable(source *XLSXSST) []string {
 	reftable := make([]string, len(source.SI))
 	for i, si := range source.SI {
@@ -26,6 +40,10 @@ func MakeSharedStringRefTable(source *XLSXSST) []string {
 	return reftable
 }
 
+// ResolveSharedString() looks up a string value by numeric index from
+// a provided reference table (just a slice of strings in the correct
+// order).  This function only exists to provide clarity or purpose
+// via it's name.
 func ResolveSharedString(reftable []string, index int) string {
 	return reftable[index]
 }

sharedstrings_test.go

@@ -7,7 +7,7 @@ import (
 	"xml"
 )
 
-
+// Test we can correctly convert a XLSXSST into a reference table using xlsx.MakeSharedStringRefTable().
 func TestMakeSharedStringRefTable(t *testing.T) {
 	var sharedstringsXML = bytes.NewBufferString(`<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <sst xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" count="4" uniqueCount="4"><si><t>Foo</t></si><si><t>Bar</t></si><si><t xml:space="preserve">Baz </t></si><si><t>Quuk</t></si></sst>`)
@@ -32,6 +32,7 @@ func TestMakeSharedStringRefTable(t *testing.T) {
 }
 
 
+// Test we can correctly resolve a numeric reference in the reference table to a string value using xlsx.ResolveSharedString().
 func TestResolveSharedString(t *testing.T) {
 	var sharedstringsXML = bytes.NewBufferString(`<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <sst xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" count="4" uniqueCount="4"><si><t>Foo</t></si><si><t>Bar</t></si><si><t xml:space="preserve">Baz </t></si><si><t>Quuk</t></si></sst>`)
@@ -48,6 +49,8 @@ func TestResolveSharedString(t *testing.T) {
 }
 
 
+// Test we can correctly unmarshal an the sharedstrings.xml file into
+// an xlsx.XLSXSST struct and it's associated children.
 func TestUnmarshallSharedStrings(t *testing.T) {
 	var sharedstringsXML = bytes.NewBufferString(`<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <sst xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" count="4" uniqueCount="4"><si><t>Foo</t></si><si><t>Bar</t></si><si><t xml:space="preserve">Baz </t></si><si><t>Quuk</t></si></sst>`)

workbook.go

@@ -1,6 +1,10 @@
 package xlsx
 
 
+// XLSXWorkbook directly maps the workbook element from the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main -
+// currently I have not checked it for completeness - it does as much
+// as I need.
 type XLSXWorkbook struct {
 	FileVersion  XLSXFileVersion
 	WorkbookPr   XLSXWorkbookPr
@@ -10,6 +14,10 @@ type XLSXWorkbook struct {
 	CalcPr       XLSXCalcPr
 }
 
+// XLSXFileVersion directly maps the fileVersion element from the
+// namespace http://schemas.openxmlformats.org/spreadsheetml/2006/main
+// - currently I have not checked it for completeness - it does as
+// much as I need.
 type XLSXFileVersion struct {
 	AppName      string "attr"
 	LastEdited   string "attr"
@@ -17,15 +25,26 @@ type XLSXFileVersion struct {
 	RupBuild     string "attr"
 }
 
+// XLSXWorkbookPr directly maps the workbookPr element from the
+// namespace http://schemas.openxmlformats.org/spreadsheetml/2006/main
+// - currently I have not checked it for completeness - it does as
+// much as I need.
 type XLSXWorkbookPr struct {
 	DefaultThemeVersion string "attr"
 }
 
+// XLSXBookViews directly maps the bookViews element from the
+// namespace http://schemas.openxmlformats.org/spreadsheetml/2006/main
+// - currently I have not checked it for completeness - it does as
+// much as I need.
 type XLSXBookViews struct {
 	WorkBookView []XLSXWorkBookView
 }
 
-
+// XLSXWorkBookView directly maps the workbookView element from the
+// namespace http://schemas.openxmlformats.org/spreadsheetml/2006/main
+// - currently I have not checked it for completeness - it does as
+// much as I need.
 type XLSXWorkBookView struct {
 	XWindow      string "attr"
 	YWindow      string "attr"
@@ -33,28 +52,48 @@ type XLSXWorkBookView struct {
 	WindowHeight string "attr"
 }
 
+// XLSXSheets directly maps the sheets element from the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main -
+// currently I have not checked it for completeness - it does as much
+// as I need.
 type XLSXSheets struct {
 	Sheet []XLSXSheet
 }
 
-
+// XLSXSheet directly maps the sheet element from the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main -
+// currently I have not checked it for completeness - it does as much
+// as I need.
 type XLSXSheet struct {
 	Name    string "attr"
 	SheetId string "attr"
 	Id      string "attr"
 }
 
-
+// XLSXDefinedNames directly maps the definedNames element from the
+// namespace http://schemas.openxmlformats.org/spreadsheetml/2006/main
+// - currently I have not checked it for completeness - it does as
+// much as I need.
 type XLSXDefinedNames struct {
 	DefinedName []XLSXDefinedName
 }
 
+
+// XLSXDefinedName directly maps the definedName element from the
+// namespace http://schemas.openxmlformats.org/spreadsheetml/2006/main
+// - currently I have not checked it for completeness - it does as
+// much as I need.
 type XLSXDefinedName struct {
 	Data         string "chardata"
 	Name         string "attr"
 	LocalSheetID string "attr"
 }
 
+
+// XLSXCalcPr directly maps the calcPr element from the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main -
+// currently I have not checked it for completeness - it does as much
+// as I need.
 type XLSXCalcPr struct {
 	CalcId string "attr"
 }

workbook_test.go

@@ -7,7 +7,9 @@ import (
 	"xml"
 )
 
-
+// Test we can succesfully unmarshal the workbook.xml file from within
+// an XLSX file and return a XLSXWorkbook struct (and associated
+// children).
 func TestUnmarshallWorkbookXML(t *testing.T) {
 	var error os.Error
 	var buf = bytes.NewBufferString(`<?xml version="1.0" encoding="UTF-8" standalone="yes"?><workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"><fileVersion appName="xl" lastEdited="4" lowestEdited="4" rupBuild="4506"/><workbookPr defaultThemeVersion="124226"/><bookViews><workbookView xWindow="120" yWindow="75" windowWidth="15135" windowHeight="7620"/></bookViews><sheets><sheet name="Sheet1" sheetId="1" r:id="rId1"/><sheet name="Sheet2" sheetId="2" r:id="rId2"/><sheet name="Sheet3" sheetId="3" r:id="rId3"/></sheets><definedNames><definedName name="monitors" localSheetId="0">Sheet1!$A$1533</definedName></definedNames><calcPr calcId="125725"/></workbook>`)

worksheet.go

@@ -1,5 +1,9 @@
 package xlsx
 
+// XLSXWorksheet directly maps the worksheet element in the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main -
+// currently I have not checked it for completeness - it does as much
+// as I need.
 type XLSXWorksheet struct {
 	Dimension     XLSXDimension
 	SheetViews    XLSXSheetViews
@@ -7,16 +11,26 @@ type XLSXWorksheet struct {
 	SheetData     XLSXSheetData
 }
 
-
+// XLSXDimension directly maps the dimension element in the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main -
+// currently I have not checked it for completeness - it does as much
+// as I need.
 type XLSXDimension struct {
 	Ref string "attr"
 }
 
+// XLSXSheetViews directly maps the sheetViews element in the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main -
+// currently I have not checked it for completeness - it does as much
+// as I need.
 type XLSXSheetViews struct {
 	SheetView []XLSXSheetView
 }
 
-
+// XLSXSheetView directly maps the sheetView element in the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main -
+// currently I have not checked it for completeness - it does as much
+// as I need.
 type XLSXSheetView struct {
 	TabSelected    string "attr"
 	WorkbookViewID string "attr"
@@ -24,28 +38,46 @@ type XLSXSheetView struct {
 }
 
 
+// XLSXSelection directly maps the selection element in the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main -
+// currently I have not checked it for completeness - it does as much
+// as I need.
 type XLSXSelection struct {
 	ActiveCell string "attr"
 	SQRef      string "attr"
 }
 
+// XLSXSheetFormatPr directly maps the sheetFormatPr element in the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main -
+// currently I have not checked it for completeness - it does as much
+// as I need.
 type XLSXSheetFormatPr struct {
 	BaseColWidth     string "attr"
 	DefaultRowHeight string "attr"
 }
 
+// XLSXSheetData directly maps the sheetData element in the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main -
+// currently I have not checked it for completeness - it does as much
+// as I need.
 type XLSXSheetData struct {
 	Row []XLSXRow
 }
 
-
+// XLSXRow directly maps the row element in the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main -
+// currently I have not checked it for completeness - it does as much
+// as I need.
 type XLSXRow struct {
 	R     string "attr"
 	Spans string "attr"
 	C     []XLSXC
 }
 
-
+// XLSXC directly maps the c element in the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main -
+// currently I have not checked it for completeness - it does as much
+// as I need.
 type XLSXC struct {
 	R string "attr"
 	T string "attr"
@@ -53,6 +85,10 @@ type XLSXC struct {
 }
 
 
+// XLSXV directly maps the v element in the namespace
+// http://schemas.openxmlformats.org/spreadsheetml/2006/main -
+// currently I have not checked it for completeness - it does as much
+// as I need.
 type XLSXV struct {
 	Data string "chardata"
 }

worksheet_test.go

@@ -6,7 +6,8 @@ import (
 	"xml"
 )
 
-
+// Test we can succesfully unmarshal the sheetN.xml files within and
+// XLSX file into an XLSXWorksheet struct (and it's related children).
 func TestUnmarshallWorksheet(t *testing.T) {
 	var sheetxml = bytes.NewBufferString(`<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"><dimension ref="A1:B2"/><sheetViews><sheetView tabSelected="1" workbookViewId="0"><selection activeCell="C2" sqref="C2"/></sheetView></sheetViews><sheetFormatPr baseColWidth="10" defaultRowHeight="15"/><sheetData><row r="1" spans="1:2"><c r="A1" t="s"><v>0</v></c><c r="B1" t="s"><v>1</v></c></row><row r="2" spans="1:2"><c r="A2" t="s"><v>2</v></c><c r="B2" t="s"><v>3</v></c></row></sheetData><pageMargins left="0.7" right="0.7" top="0.78740157499999996" bottom="0.78740157499999996" header="0.3" footer="0.3"/></worksheet>`)