Add doc comments for exported symbols.

Author: dsymonds

client.go

@@ -35,6 +35,7 @@ var cookieBaseURL = &url.URL{
 	Host:   "www.opal.com.au",
 }
 
+// NewClient constructs a new Client.
 func NewClient(as AuthStore) (*Client, error) {
 	a, err := as.Load()
 	if err != nil {
@@ -57,11 +58,13 @@ func NewClient(as AuthStore) (*Client, error) {
 	return c, nil
 }
 
+// WriteConfig writes the configuration to the client's AuthStore.
 func (c *Client) WriteConfig() error {
 	c.a.Cookies = c.hc.Jar.Cookies(cookieBaseURL)
 	return c.as.Save(c.a)
 }
 
+// Overview fetches the account overview.
 func (c *Client) Overview() (*Overview, error) {
 	body, err := c.get("https://www.opal.com.au/registered/index")
 	if err != nil {
@@ -70,13 +73,15 @@ func (c *Client) Overview() (*Overview, error) {
 	return parseOverview(body)
 }
 
+// An ActivityRequest configures the operation of Activity.
 type ActivityRequest struct {
 	CardIndex int
 	// Offset is how many pages into the past to fetch.
 	// Zero is the most recent activity.
 	Offset int
 }
 
+// Activity fetches a subset of the activity data for a card.
 func (c *Client) Activity(req ActivityRequest) (*Activity, error) {
 	u := fmt.Sprintf("https://www.opal.com.au/registered/opal-card-transactions/?cardIndex=%d", req.CardIndex)
 	if req.Offset > 0 {
@@ -155,13 +160,18 @@ func (c *Client) login() error {
 	return nil
 }
 
+// An AuthStore is an interface for loading and saving authentication information.
+// See FileAuthStore for a file-based implementation.
 type AuthStore interface {
 	Load() (*Auth, error)
 	Save(*Auth) error
 }
 
+// DefaultAuthFile is a default place to store authentication information.
+// Pass this to FileAuthStore if an alternate path isn't required.
 var DefaultAuthFile = filepath.Join(os.Getenv("HOME"), ".opal")
 
+// FileAuthStore returns an AuthStore that stores authentication information in a named file.
 func FileAuthStore(filename string) AuthStore {
 	return fileAuthStore{filename}
 }

parse.go

@@ -13,10 +13,12 @@ import (
 	"code.google.com/p/go.net/html/atom"
 )
 
+// Overview represents an overview of an Opal account.
 type Overview struct {
 	Cards []Card
 }
 
+// Card represents a single Opal card.
 type Card struct {
 	Name    string // either a name or number
 	Balance int    // in cents
@@ -101,11 +103,15 @@ func parseOverview(input []byte) (*Overview, error) {
 	return o, nil
 }
 
+// Activity represents a subset of activity for a single card.
 type Activity struct {
 	CardName     string
 	Transactions []*Transaction
 }
 
+// Transaction represents a single transaction on a card.
+// This may be a single journey, or a top-up.
+// Not all fields may be set.
 type Transaction struct {
 	Number        int
 	When          time.Time