plumbing: improve documentation (Fix #242)

Author: ajnavarro

plumbing/format/config/section.go

@@ -2,6 +2,27 @@ package config
 
 import "strings"
 
+// Section is the representation of a section inside git configuration files.
+// Each Section contains Options that are used by both the Git plumbing
+// and the porcelains.
+// Sections can be further divided into subsections. To begin a subsection
+// put its name in double quotes, separated by space from the section name,
+// in the section header, like in the example below:
+//
+//     [section "subsection"]
+//
+// All the other lines (and the remainder of the line after the section header)
+// are recognized as option variables, in the form "name = value" (or just name,
+// which is a short-hand to say that the variable is the boolean "true").
+// The variable names are case-insensitive, allow only alphanumeric characters
+// and -, and must start with an alphabetic character:
+//
+//     [section "subsection1"]
+//         option1 = value1
+//         option2
+//     [section "subsection2"]
+//         option3 = value2
+//
 type Section struct {
 	Name        string
 	Options     Options
@@ -17,29 +38,38 @@ type Sections []*Section
 
 type Subsections []*Subsection
 
+// IsName checks if the name provided is equals to the Section name, case insensitive.
 func (s *Section) IsName(name string) bool {
 	return strings.ToLower(s.Name) == strings.ToLower(name)
 }
 
+// Option return the value for the specified key. Empty string is returned if
+// key does not exists.
 func (s *Section) Option(key string) string {
 	return s.Options.Get(key)
 }
 
+// AddOption adds a new Option to the Section. The updated Section is returned.
 func (s *Section) AddOption(key string, value string) *Section {
 	s.Options = s.Options.withAddedOption(key, value)
 	return s
 }
 
+// SetOption adds a new Option to the Section. If the option already exists, is replaced.
+// The updated Section is returned.
 func (s *Section) SetOption(key string, value string) *Section {
 	s.Options = s.Options.withSettedOption(key, value)
 	return s
 }
 
+// Remove an option with the specified key. The updated Section is returned.
 func (s *Section) RemoveOption(key string) *Section {
 	s.Options = s.Options.withoutOption(key)
 	return s
 }
 
+// Subsection returns a Subsection from the specified Section. If the
+// Subsection does not exists, new one is created and added to Section.
 func (s *Section) Subsection(name string) *Subsection {
 	for i := len(s.Subsections) - 1; i >= 0; i-- {
 		ss := s.Subsections[i]
@@ -53,6 +83,7 @@ func (s *Section) Subsection(name string) *Subsection {
 	return ss
 }
 
+// HasSubsection checks if the Section has a Subsection with the specified name.
 func (s *Section) HasSubsection(name string) bool {
 	for _, ss := range s.Subsections {
 		if ss.IsName(name) {
@@ -63,24 +94,31 @@ func (s *Section) HasSubsection(name string) bool {
 	return false
 }
 
+// IsName checks if the name of the subsection is exactly the specified name.
 func (s *Subsection) IsName(name string) bool {
 	return s.Name == name
 }
 
+// Option returns an option with the specified key. If the option does not exists,
+// empty spring will be returned.
 func (s *Subsection) Option(key string) string {
 	return s.Options.Get(key)
 }
 
+// AddOption adds a new Option to the Subsection. The updated Subsection is returned.
 func (s *Subsection) AddOption(key string, value string) *Subsection {
 	s.Options = s.Options.withAddedOption(key, value)
 	return s
 }
 
+// SetOption adds a new Option to the Subsection. If the option already exists, is replaced.
+// The updated Subsection is returned.
 func (s *Subsection) SetOption(key string, value string) *Subsection {
 	s.Options = s.Options.withSettedOption(key, value)
 	return s
 }
 
+// RemoveOption removes the option with the specified key. The updated Subsection is returned.
 func (s *Subsection) RemoveOption(key string) *Subsection {
 	s.Options = s.Options.withoutOption(key)
 	return s

plumbing/format/packfile/decoder.go

@@ -300,8 +300,11 @@ func (d *Decoder) newObject() plumbing.EncodedObject {
 	return d.o.NewEncodedObject()
 }
 
-// DecodeObjectAt reads an object at the given location, if Decode wasn't called
-// previously objects offset should provided using the SetOffsets method
+// DecodeObjectAt reads an object at the given location. Every EncodedObject
+// returned is added into a internal index. This is intended to be able to regenerate
+// objects from deltas (offset deltas or reference deltas) without an package index
+// (.idx file). If Decode wasn't called previously objects offset should provided
+// using the SetOffsets method.
 func (d *Decoder) DecodeObjectAt(offset int64) (plumbing.EncodedObject, error) {
 	if !d.s.IsSeekable {
 		return nil, ErrNonSeekable

plumbing/format/packfile/diff_delta.go

@@ -14,8 +14,10 @@ const (
 	maxCopyLen = 0xffff
 )
 
-// GetDelta returns an offset delta that knows the way of how to transform
-// base object to target object
+// GetDelta returns an EncodedObject of type OFSDeltaObject. Base and Target object,
+// will be loaded into memory to be able to create the delta object.
+// To generate target again, you will need the obtained object and "base" one.
+// Error will be returned if base or target object cannot be read.
 func GetDelta(base, target plumbing.EncodedObject) (plumbing.EncodedObject, error) {
 	br, err := base.Reader()
 	if err != nil {

plumbing/format/packfile/encoder.go

@@ -23,7 +23,8 @@ type Encoder struct {
 }
 
 // NewEncoder creates a new packfile encoder using a specific Writer and
-// EncodedObjectStorer
+// EncodedObjectStorer. By default deltas used to generate the packfile will be
+// OFSDeltaObject. To use Reference deltas, set useRefDeltas to true.
 func NewEncoder(w io.Writer, s storer.EncodedObjectStorer, useRefDeltas bool) *Encoder {
 	h := plumbing.Hasher{
 		Hash: sha1.New(),

plumbing/format/pktline/encoder.go

@@ -116,7 +116,8 @@ func (e *Encoder) EncodeString(payloads ...string) error {
 }
 
 // Encodef encodes a single pkt-line with the payload formatted as
-// the format specifier and the rest of the arguments suggest.
+// the format specifier. The rest of the arguments will be used in
+// the format string.
 func (e *Encoder) Encodef(format string, a ...interface{}) error {
 	return e.EncodeString(
 		fmt.Sprintf(format, a...),

plumbing/storer/reference.go

@@ -13,15 +13,15 @@ const MaxResolveRecursion = 1024
 // is exceeded
 var ErrMaxResolveRecursion = errors.New("max. recursion level reached")
 
-// ReferenceStorer generic storage of references
+// ReferenceStorer is a generic storage of references.
 type ReferenceStorer interface {
 	SetReference(*plumbing.Reference) error
 	Reference(plumbing.ReferenceName) (*plumbing.Reference, error)
 	IterReferences() (ReferenceIter, error)
 	RemoveReference(plumbing.ReferenceName) error
 }
 
-// ReferenceIter is a generic closable interface for iterating over references
+// ReferenceIter is a generic closable interface for iterating over references.
 type ReferenceIter interface {
 	Next() (*plumbing.Reference, error)
 	ForEach(func(*plumbing.Reference) error) error
@@ -82,7 +82,7 @@ func (iter *ReferenceSliceIter) Close() {
 	iter.pos = len(iter.series)
 }
 
-// ResolveReference resolve a SymbolicReference to a HashReference
+// ResolveReference resolves a SymbolicReference to a HashReference.
 func ResolveReference(s ReferenceStorer, n plumbing.ReferenceName) (*plumbing.Reference, error) {
 	r, err := s.Reference(n)
 	if err != nil || r == nil {

plumbing/storer/shallow.go

@@ -2,8 +2,8 @@ package storer
 
 import "srcd.works/go-git.v4/plumbing"
 
-// ShallowStorer storage of references to shallow commits by hash, meaning that
-// these commits have missing parents because of a shallow fetch.
+// ShallowStorer is a storage of references to shallow commits by hash,
+// meaning that these commits have missing parents because of a shallow fetch.
 type ShallowStorer interface {
 	SetShallow([]plumbing.Hash) error
 	Shallow() ([]plumbing.Hash, error)