From 059a0be78399cdb0648bd514c5b179819d84403d Mon Sep 17 00:00:00 2001 From: Antonio Jesus Navarro Perez Date: Thu, 23 Feb 2017 17:07:08 +0100 Subject: plumbing: improve documentation (Fix #242) --- plumbing/format/config/section.go | 38 ++++++++++++++++++++++++++++++++++ plumbing/format/packfile/decoder.go | 7 +++++-- plumbing/format/packfile/diff_delta.go | 6 ++++-- plumbing/format/packfile/encoder.go | 3 ++- plumbing/format/pktline/encoder.go | 3 ++- plumbing/storer/reference.go | 6 +++--- plumbing/storer/shallow.go | 4 ++-- 7 files changed, 56 insertions(+), 11 deletions(-) diff --git a/plumbing/format/config/section.go b/plumbing/format/config/section.go index 1844913..547da1e 100644 --- a/plumbing/format/config/section.go +++ b/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 diff --git a/plumbing/format/packfile/decoder.go b/plumbing/format/packfile/decoder.go index 4e102c7..cd439b0 100644 --- a/plumbing/format/packfile/decoder.go +++ b/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 diff --git a/plumbing/format/packfile/diff_delta.go b/plumbing/format/packfile/diff_delta.go index 7b2e4ca..c25e194 100644 --- a/plumbing/format/packfile/diff_delta.go +++ b/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 { diff --git a/plumbing/format/packfile/encoder.go b/plumbing/format/packfile/encoder.go index 96fe4b4..a0a13f8 100644 --- a/plumbing/format/packfile/encoder.go +++ b/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(), diff --git a/plumbing/format/pktline/encoder.go b/plumbing/format/pktline/encoder.go index 753b225..797b813 100644 --- a/plumbing/format/pktline/encoder.go +++ b/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...), diff --git a/plumbing/storer/reference.go b/plumbing/storer/reference.go index 692fe88..b408778 100644 --- a/plumbing/storer/reference.go +++ b/plumbing/storer/reference.go @@ -13,7 +13,7 @@ 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) @@ -21,7 +21,7 @@ type ReferenceStorer interface { 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 { diff --git a/plumbing/storer/shallow.go b/plumbing/storer/shallow.go index f93060d..a38e751 100644 --- a/plumbing/storer/shallow.go +++ b/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) -- cgit