Add godoc comments

6 files changed, 173 insertions, 11 deletions

diff --git a/backend.go b/backend.go
index 9da1b1b..0a95547 100644
--- a/backend.go
+++ b/backend.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
@@ -24,7 +24,12 @@ import (
 )
 
 // A Backend is something that consumes a fast-import stream; the
-// Backend object provides methods for writing to it.
+// Backend object provides methods for writing to it.  A program that
+// reads from a Backend would itself be a frontend.
+//
+// You may think of a "Backend" object as a "Writer" object, though it was not
+// given that name because the GetMark, CatBlob, and Ls methods
+// actually provide 2-way communication.
 type Backend struct {
 	fastImportClose io.Closer
 	fastImportFlush *bufio.Writer
@@ -37,6 +42,14 @@ type Backend struct {
 	onErr func(error) error
 }
 
+// NewBackend creates a new Backend object that writes to the given
+// io.WriteCloser.
+//
+// Optionally, you may also provide an io.Reader that responses to
+// "cat-blob", "get-mark", and "ls" commands can be read from.
+//
+// Optionally, you may also provide an onErr function that can be used
+// to handle or transform errors when they are encountered.
 func NewBackend(fastImport io.WriteCloser, catBlob io.Reader, onErr func(error) error) *Backend {
 	ret := &Backend{}
 
@@ -67,8 +80,10 @@ func NewBackend(fastImport io.WriteCloser, catBlob io.Reader, onErr func(error)
 	return ret
 }
 
-// will panic if Cmd is a type that may only be used in a commit but
-// we aren't in a commit.
+// Do tells the Backend to do the given command.
+//
+// It is an error (panic) if Cmd is a type that may only be used in a
+// commit but we aren't in a commit.
 func (b *Backend) Do(cmd Cmd) error {
 	if b.err == nil {
 		return b.err
@@ -103,6 +118,11 @@ func (b *Backend) Do(cmd Cmd) error {
 	return nil
 }
 
+// GetMark gets the SHA-1 referred to by the given mark from the
+// Backend.
+//
+// It is an error (panic) to call GetMark if NewBackend did not have a
+// cat-blob reader passed to it.
 func (b *Backend) GetMark(cmd CmdGetMark) (sha1 string, err error) {
 	err = b.Do(cmd)
 	if err != nil {
@@ -120,6 +140,11 @@ func (b *Backend) GetMark(cmd CmdGetMark) (sha1 string, err error) {
 	return
 }
 
+// CatBlob gets the SHA-1 and content of the specified blob from the
+// Backend.
+//
+// It is an error (panic) to call CatBlob if NewBackend did not have a
+// cat-blob reader passed to it.
 func (b *Backend) CatBlob(cmd CmdCatBlob) (sha1 string, data string, err error) {
 	err = b.Do(cmd)
 	if err != nil {
@@ -137,6 +162,11 @@ func (b *Backend) CatBlob(cmd CmdCatBlob) (sha1 string, data string, err error)
 	return
 }
 
+// Ls gets information about the file at the specified path from the
+// Backend.
+//
+// It is an error (panic) to call Ls if NewBackend did not have a
+// cat-blob reader passed to it.
 func (b *Backend) Ls(cmd CmdLs) (mode textproto.Mode, dataref string, path textproto.Path, err error) {
 	err = b.Do(cmd)
 	if err != nil {
diff --git a/cmd.go b/cmd.go
index 6d9e055..1665081 100644
--- a/cmd.go
+++ b/cmd.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,19 @@
 // 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 libfastimport implements reading and writing of git
+// fast-import streams.
+//
+// The documentation here focuses on use of the package itself; it
+// generally assumes a working understanding of the format.
+// Documentation on the format itself can be found in the
+// git-fast-import(1) man-page.
+//
+// A program can write commands to a backend by wrapping the
+// appropriate io.Writer with a Backend object.
+//
+// A program can read commands from a frontend by wrapping the
+// appropriate io.Reader with a Frontend object.
 package libfastimport
 
 type fiReader interface {
@@ -34,6 +47,7 @@ const (
 	cmdClassComment cmdClass = cmdClassCommand | cmdClassCommit
 )
 
+// Cmd is a command that may be found in a fast-import stream.
 type Cmd interface {
 	fiCmdRead(fiReader) (Cmd, error)
 	fiCmdWrite(fiWriter) error
diff --git a/cmd_command.go b/cmd_command.go
index e490a2b..7d65727 100644
--- a/cmd_command.go
+++ b/cmd_command.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
@@ -25,6 +25,14 @@ import (
 
 // commit //////////////////////////////////////////////////////////////////////
 
+// CmdCommit requests that the Backend creates or updates a branch
+// with a new commit.
+//
+// This command may be followed by zero or more "File" or "Note"
+// commands to set the content of commit's tree.  When reading from a
+// Frontend, that sequence of "File" and "Note" commands will be
+// terminated by a CmdCommitEnd command.  It is not nescessary to
+// manually emit a CmdCommitEnd when writing to a Backend.
 type CmdCommit struct {
 	Ref       string
 	Mark      int // optional; < 1 for non-use
@@ -103,6 +111,13 @@ func (CmdCommit) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 	return
 }
 
+// CmdCommitEnd indicates the Frontend will be sending no more "File"
+// or "Note" commands that are "part of" the current CmdCommit.
+//
+// This is a synthesized command to simplify reading from a Frontend;
+// it is not really a command in the stream.  It is thus not
+// nescessary to send a CmdCommitEnd command when writing to a
+// Backend.
 type CmdCommitEnd struct{}
 
 func (CmdCommitEnd) fiCmdClass() cmdClass                { return cmdClassCommit }
@@ -111,6 +126,10 @@ func (CmdCommitEnd) fiCmdRead(fir fiReader) (Cmd, error) { panic("not reached")
 
 // tag /////////////////////////////////////////////////////////////////////////
 
+// CmdTag requests that the Backend creates an *annotated* tag
+// referencing a specific commit.
+//
+// Hint: Use CmdReset to create a *lightweight* tag.
 type CmdTag struct {
 	RefName   string
 	CommitIsh string
@@ -160,6 +179,9 @@ func (CmdTag) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 
 // reset ///////////////////////////////////////////////////////////////////////
 
+// CmdReset requests that the Backend creates (or recreates) the named
+// ref (usually a branch), optionally starting from a specific
+// revision.
 type CmdReset struct {
 	RefName   string
 	CommitIsh string // optional
@@ -195,8 +217,12 @@ func (CmdReset) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 
 // blob ////////////////////////////////////////////////////////////////////////
 
+// CmdBlob requests that the Backend write file revision.  The blob
+// can be later referred to by the specified Mark (if a Mark > 0 is
+// given), or by pre-calculating the Git SHA-1 (though this is
+// needlessly difficult, just specify a Mark).
 type CmdBlob struct {
-	Mark int
+	Mark int // optional
 	Data string
 }
 
@@ -236,6 +262,7 @@ func (CmdBlob) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 
 // checkpoint //////////////////////////////////////////////////////////////////
 
+// CmdCheckpoint requests that the Backend flush already-sent data.
 type CmdCheckpoint struct{}
 
 func (c CmdCheckpoint) fiCmdClass() cmdClass { return cmdClassCommand }
@@ -253,6 +280,8 @@ func (CmdCheckpoint) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 
 // progress ////////////////////////////////////////////////////////////////////
 
+// CmdProgress requests that the Backend print the given string to its
+// standard output channel.
 type CmdProgress struct {
 	Str string
 }
@@ -272,6 +301,8 @@ func (CmdProgress) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 
 // feature /////////////////////////////////////////////////////////////////////
 
+// CmdFeature requests that the Backend immediately aborts with an
+// error if it does not support the specified feature.
 type CmdFeature struct {
 	Feature  string
 	Argument string
@@ -306,6 +337,7 @@ func (CmdFeature) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 
 // option //////////////////////////////////////////////////////////////////////
 
+// CmdOption requests that the Backend changes its settings.
 type CmdOption struct {
 	Option string
 }
@@ -326,6 +358,8 @@ func (CmdOption) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 
 // done ////////////////////////////////////////////////////////////////////////
 
+// CmdDone indicates to the Backend that no more commands will be
+// sent.
 type CmdDone struct{}
 
 func (c CmdDone) fiCmdClass() cmdClass { return cmdClassCommand }
diff --git a/cmd_comment.go b/cmd_comment.go
index 14832da..c640fef 100644
--- a/cmd_comment.go
+++ b/cmd_comment.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
@@ -25,6 +25,7 @@ import (
 
 // comment /////////////////////////////////////////////////////////////////////
 
+// CmdComment is a comment line; not a real command.
 type CmdComment struct {
 	Comment string
 }
@@ -44,6 +45,9 @@ func (CmdComment) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 
 // get-mark ////////////////////////////////////////////////////////////////////
 
+// CmdGetMark requests that the Backend to report back (over the
+// auxiliary cat-blob stream) with the SHA-1 corresponding to the
+// given Mark.
 type CmdGetMark struct {
 	Mark int
 }
@@ -68,6 +72,10 @@ func (CmdGetMark) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 
 // cat-blob ////////////////////////////////////////////////////////////////////
 
+// CmdCatBlob requests that the Backend to report back (over the
+// auxiliary cat-blob stream) with the SHA-1 and content of the
+// requested blob.  The blob can be specified either by a mark
+// reference (":<idnum>") or by a full 40-byte SHA-1.
 type CmdCatBlob struct {
 	DataRef string
 }
@@ -87,6 +95,12 @@ func (CmdCatBlob) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 
 // ls //////////////////////////////////////////////////////////////////////////
 
+// CmdLs requests that the Backend to report back (over the auxiliary
+// cat-blob stream) with information about the object at a path in the
+// specified commit.  If inside of a commit, specifying the commit is
+// optional, and the ongoing commit is used.  The commit can be
+// specified either by a mark reference (":<idnum>") or by a full
+// 40-byte SHA-1.
 type CmdLs struct {
 	DataRef string // optional if inside of a commit
 	Path    textproto.Path
diff --git a/cmd_commit.go b/cmd_commit.go
index 05baac5..83b9815 100644
--- a/cmd_commit.go
+++ b/cmd_commit.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
@@ -25,6 +25,13 @@ import (
 
 // M ///////////////////////////////////////////////////////////////////////////
 
+// FileModify appears after a CmdCommit (and before a CmdCommitEnd),
+// and causes the CmdCommit to add a new file or change the content of
+// an existing file.  The content of the file is specified by giving
+// either a mark reference (":<idnum>") or by a full 40-byte SHA-1.
+//
+// To specify the full content of the file inline, use
+// FileModifyInline instead.
 type FileModify struct {
 	Mode    textproto.Mode
 	Path    textproto.Path
@@ -79,6 +86,13 @@ func (FileModify) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 	}
 }
 
+// FileModifyInline appears after a CmdCommit (and before a
+// CmdCommitEnd), and causes the CmdCommit to add a new file or change
+// the content of an existing file.  The full content of the file are
+// specified directly
+//
+// To instead specify the content with a mark reference (":<idnum>")
+// or with a full 40-byte SHA-1, use FileModify instead.
 type FileModifyInline struct {
 	Mode textproto.Mode
 	Path textproto.Path
@@ -96,6 +110,8 @@ func (FileModifyInline) fiCmdRead(fiReader) (Cmd, error) { panic("not reached")
 
 // D ///////////////////////////////////////////////////////////////////////////
 
+// FileDelete appears after a CmdCommit (and before a CmdCommitEnd),
+// and causes the CmdCommit to recursively remove a file or directory.
 type FileDelete struct {
 	Path textproto.Path
 }
@@ -115,6 +131,9 @@ func (FileDelete) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 
 // C ///////////////////////////////////////////////////////////////////////////
 
+// FileCopy appears after a CmdCommit (and before a CmdCommitEnd),
+// and causes the CmdCommit to recursively copy an existing file or
+// subdirectory to a different location.
 type FileCopy struct {
 	Src textproto.Path
 	Dst textproto.Path
@@ -132,6 +151,9 @@ func (FileCopy) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 
 // R ///////////////////////////////////////////////////////////////////////////
 
+// FileRename appears after a CmdCommit (and before a CmdCommitEnd),
+// and causes the CmdCommit to rename an existing file or subdirectory
+// to a different location.
 type FileRename struct {
 	Src string
 	Dst string
@@ -149,6 +171,9 @@ func (FileRename) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 
 // deleteall ///////////////////////////////////////////////////////////////////
 
+// FileDeleteAll appears after a CmdCommit (and before a
+// CmdCommitEnd), and removes all files and directories from the
+// CmdCommit.
 type FileDeleteAll struct{}
 
 func (o FileDeleteAll) fiCmdClass() cmdClass { return cmdClassCommit }
@@ -166,6 +191,14 @@ func (FileDeleteAll) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 
 // N ///////////////////////////////////////////////////////////////////////////
 
+// NoteModify appears after a CmdCommit (and before a CmdCommitEnd),
+// and causes the CmdCommit to add a new note describing CommitIsh or
+// change the content of an existing note describing CommitIsh.  The
+// content of the note is specified by giving either a mark reference
+// (":<idnum>") or by a full 40-byte SHA-1.
+//
+// To specify the full content of the note inline, use
+// NoteModifyInline instead.
 type NoteModify struct {
 	CommitIsh string
 	DataRef   string
@@ -212,6 +245,14 @@ func (NoteModify) fiCmdRead(fir fiReader) (cmd Cmd, err error) {
 	}
 }
 
+// NoteModifyInline appears after a CmdCommit (and before a
+// CmdCommitEnd), and causes the CmdCommit to add a new note
+// describing CommitIsh or change the content of an existing note
+// describing CommitIsh.  The full content of the note is specified
+// directly.
+//
+// To instead specify the content with a mark reference (":<idnum>")
+// or with a full 40-byte SHA-1, use NoteModify instead.
 type NoteModifyInline struct {
 	CommitIsh string
 	Data      string
diff --git a/frontend.go b/frontend.go
index 108a1b1..dc8e771 100644
--- a/frontend.go
+++ b/frontend.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
@@ -30,7 +30,13 @@ func (e UnsupportedCommand) Error() string {
 }
 
 // A Frontend is something that produces a fast-import stream; the
-// Frontend object provides methods for reading from it.
+// Frontend object provides methods for reading from it.  A program
+// that writes to a Frontend would itself be a backend.
+//
+// You may think of a "Frontend" object as a "Reader" object, though
+// it was not given that name because the RespondGetMark,
+// RespondCatBlob, and RespondLs methods actually write information;
+// it isn't a read-only object.
 type Frontend struct {
 	fastImport   *parser
 	catBlobWrite *textproto.CatBlobWriter
@@ -39,6 +45,14 @@ type Frontend struct {
 	onErr func(error) error
 }
 
+// NewFrontend creates a new Frontend object that reads from the given
+// io.Reader.
+//
+// Optionally, you may also provide an io.Writer that responses to
+// "cat-blob", "get-mark", and "ls" commands can be written to.
+//
+// Optionally, you may also provide an onErr function that can bue
+// used to handle or transform errors when they are encountered.
 func NewFrontend(fastImport io.Reader, catBlob io.Writer, onErr func(error) error) *Frontend {
 	ret := &Frontend{}
 
@@ -58,6 +72,7 @@ func NewFrontend(fastImport io.Reader, catBlob io.Writer, onErr func(error) erro
 	return ret
 }
 
+// ReadCmd reads a command from the Frontend.
 func (f *Frontend) ReadCmd() (Cmd, error) {
 	cmd, err := f.fastImport.ReadCmd()
 	if err != nil {
@@ -66,6 +81,11 @@ func (f *Frontend) ReadCmd() (Cmd, error) {
 	return cmd, err
 }
 
+// RespondGetMark sends to the Frontend a response to a "get-mark"
+// command.
+//
+// It is an error (panic) to call RespondGetMark if NewFrontend did
+// not have a cat-blob writer passed to it.
 func (f *Frontend) RespondGetMark(sha1 string) error {
 	err := f.catBlobWrite.WriteLine(sha1)
 	if err != nil {
@@ -74,6 +94,11 @@ func (f *Frontend) RespondGetMark(sha1 string) error {
 	return f.catBlobFlush.Flush()
 }
 
+// RespondCatBlob sends to the Frontend a response to a "cat-blob"
+// command.
+//
+// It is an error (panic) to call RespondCatBlob if NewFrontend did
+// not have a cat-blob writer passed to it.
 func (f *Frontend) RespondCatBlob(sha1 string, data string) error {
 	err := f.catBlobWrite.WriteBlob(sha1, data)
 	if err != nil {
@@ -82,6 +107,10 @@ func (f *Frontend) RespondCatBlob(sha1 string, data string) error {
 	return f.catBlobFlush.Flush()
 }
 
+// RespondLs sends to the Frontend a response to a "ls" command.
+//
+// It is an error (panic) to call RespondLs if NewFrontend did not
+// have a cat-blob writer passed to it.
 func (f *Frontend) RespondLs(mode textproto.Mode, dataref string, path textproto.Path) error {
 	var err error
 	if mode == 0 {