1 files changed, 33 insertions, 1 deletions

diff --git a/textproto/io.go b/textproto/io.go
index da73db9..dde5470 100644
--- a/textproto/io.go
+++ b/textproto/io.go
@@ -1,4 +1,4 @@
-// Copyright (C) 2017  Luke Shumaker <lukeshu@lukeshu.com>
+// Copyright (C) 2017-2018  Luke Shumaker <lukeshu@lukeshu.com>
 //
 // This program is free software: you can redistribute it and/or modify
 // it under the terms of the GNU Affero General Public License as published by
@@ -13,6 +13,14 @@
 // You should have received a copy of the GNU Affero General Public License
 // along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
+// Package textproto implements low-level details of the fast-import
+// format.
+//
+// This package deals with parsing and marshalling idiosyncratic
+// datatypes used by the format (Ident tuples, 18-bit Mode numbers,
+// oddly-quoted Path strings), and abstracting over special-case
+// commands that break the "line-based" nature of the format (the
+// "data" command, responses to the "cat-blob" command).
 package textproto
 
 import (
@@ -23,6 +31,7 @@ import (
 	"strings"
 )
 
+// FIReader is a low-level parser of a fast-import stream.
 type FIReader struct {
 	r *bufio.Reader
 
@@ -30,12 +39,16 @@ type FIReader struct {
 	err  error
 }
 
+// NewFIReader creates a new FIReader parser.
 func NewFIReader(r io.Reader) *FIReader {
 	return &FIReader{
 		r: bufio.NewReader(r),
 	}
 }
 
+// ReadLine reads a "line" from the stream; with special handling for
+// the "data" command, which isn't really a single line, but rather
+// contains arbitrary binary data.
 func (fir *FIReader) ReadLine() (line string, err error) {
 	for len(line) <= 1 {
 		line, err = fir.r.ReadString('\n')
@@ -73,21 +86,26 @@ func (fir *FIReader) ReadLine() (line string, err error) {
 	return
 }
 
+// FIWriter is a low-level marshaller of a fast-import stream.
 type FIWriter struct {
 	w io.Writer
 }
 
+// NewFIWriter creates a new FIWriter marshaller.
 func NewFIWriter(w io.Writer) *FIWriter {
 	return &FIWriter{
 		w: w,
 	}
 }
 
+// WriteLine writes an ordinary line to the stream; arguments are
+// handled similarly to fmt.Println.
 func (fiw *FIWriter) WriteLine(a ...interface{}) error {
 	_, err := fmt.Fprintln(fiw.w, a...)
 	return err
 }
 
+// WriteData writes a 'data' command to the stream.
 func (fiw *FIWriter) WriteData(data string) error {
 	err := fiw.WriteLine("data", len(data))
 	if err != nil {
@@ -97,16 +115,22 @@ func (fiw *FIWriter) WriteData(data string) error {
 	return err
 }
 
+// CatBlobReader is a low-level parser of an fast-import auxiliary
+// "cat-blob" stream.
 type CatBlobReader struct {
 	r *bufio.Reader
 }
 
+// NewCatBlobReader creates a new CatBlobReader parser.
 func NewCatBlobReader(r io.Reader) *CatBlobReader {
 	return &CatBlobReader{
 		r: bufio.NewReader(r),
 	}
 }
 
+// ReadLine reads a response from the stream; with special handling
+// for responses to "cat-blob" commands, which contain multiple
+// newline characters.
 func (cbr *CatBlobReader) ReadLine() (line string, err error) {
 	for len(line) <= 1 {
 		line, err = cbr.r.ReadString('\n')
@@ -141,21 +165,29 @@ func (cbr *CatBlobReader) ReadLine() (line string, err error) {
 	return
 }
 
+// CatBlobWriter is a low-level marshaller for an auxiliary cat-blob
+// stream.
 type CatBlobWriter struct {
 	w io.Writer
 }
 
+// NewCatBlobWriter creates a new CatBlobWriter marshaller.
 func NewCatBlobWriter(w io.Writer) *CatBlobWriter {
 	return &CatBlobWriter{
 		w: w,
 	}
 }
 
+// WriteLine writes a response (to a command OTHER THAN "cat-blob") to
+// the stream; arguments are handled similarly to fmt.Println.
+//
+// Use WriteBlob instead to write responses to "cat-blob" commands.
 func (cbw *CatBlobWriter) WriteLine(a ...interface{}) error {
 	_, err := fmt.Fprintln(cbw.w, a...)
 	return err
 }
 
+// WriteBlob writes a response to a "cat-blob" command to the stream.
 func (cbw *CatBlobWriter) WriteBlob(sha1 string, data string) error {
 	err := cbw.WriteLine(sha1, "blob", len(data))
 	if err != nil {