config: documentation improvements

3 files changed, 44 insertions, 32 deletions

diff --git a/config/config.go b/config/config.go
index bffb125..fc6d84c 100644
--- a/config/config.go
+++ b/config/config.go
@@ -6,7 +6,7 @@ import (
 	"errors"
 	"fmt"
 
-	"gopkg.in/src-d/go-git.v4/plumbing/format/config"
+	format "gopkg.in/src-d/go-git.v4/plumbing/format/config"
 )
 
 const (
@@ -30,24 +30,28 @@ var (
 )
 
 // Config contains the repository configuration
-// https://www.kernel.org/pub/software/scm/git/docs/git-config.html
+// ftp://www.kernel.org/pub/software/scm/git/docs/git-config.html#FILES
 type Config struct {
+	// Core variables
 	Core struct {
+		// IsBare if true this repository is assumed to be bare and has no
+		// working directory associated with it
 		IsBare bool
 	}
+	// Remote list of repository remotes
 	Remotes map[string]*RemoteConfig
 
 	// contains the raw information of a config file, the main goal is preserve
-	// the parsed information from the original format, to avoid miss not
-	// supported properties
-	raw *config.Config
+	// the parsed information from the original format, to avoid missing
+	// unsupported features.
+	raw *format.Config
 }
 
 // NewConfig returns a new empty Config
 func NewConfig() *Config {
 	return &Config{
 		Remotes: make(map[string]*RemoteConfig, 0),
-		raw:     config.New(),
+		raw:     format.New(),
 	}
 }
 
@@ -77,9 +81,9 @@ const (
 // Unmarshal parses a git-config file and stores it
 func (c *Config) Unmarshal(b []byte) error {
 	r := bytes.NewBuffer(b)
-	d := config.NewDecoder(r)
+	d := format.NewDecoder(r)
 
-	c.raw = config.New()
+	c.raw = format.New()
 	if err := d.Decode(c.raw); err != nil {
 		return err
 	}
@@ -112,7 +116,7 @@ func (c *Config) Marshal() ([]byte, error) {
 	c.marshalRemotes()
 
 	buf := bytes.NewBuffer(nil)
-	if err := config.NewEncoder(buf).Encode(c.raw); err != nil {
+	if err := format.NewEncoder(buf).Encode(c.raw); err != nil {
 		return nil, err
 	}
 
@@ -126,7 +130,7 @@ func (c *Config) marshalCore() {
 
 func (c *Config) marshalRemotes() {
 	s := c.raw.Section(remoteSection)
-	s.Subsections = make(config.Subsections, len(c.Remotes))
+	s.Subsections = make(format.Subsections, len(c.Remotes))
 
 	var i int
 	for _, r := range c.Remotes {
@@ -135,13 +139,18 @@ func (c *Config) marshalRemotes() {
 	}
 }
 
-// RemoteConfig contains the configuration for a given repository
+// RemoteConfig contains the configuration for a given remote repository
 type RemoteConfig struct {
-	Name  string
-	URL   string
+	// Name of the remote
+	Name string
+	// URL the URL of a remote repository
+	URL string
+	// Fetch the default set of "refspec" for fetch operation
 	Fetch []RefSpec
 
-	raw *config.Subsection
+	// raw representation of the subsection, filled by marshal or unmarshal are
+	// called
+	raw *format.Subsection
 }
 
 // Validate validate the fields and set the default values
@@ -161,7 +170,7 @@ func (c *RemoteConfig) Validate() error {
 	return nil
 }
 
-func (c *RemoteConfig) unmarshal(s *config.Subsection) {
+func (c *RemoteConfig) unmarshal(s *format.Subsection) {
 	c.raw = s
 
 	fetch := []RefSpec{}
@@ -177,9 +186,9 @@ func (c *RemoteConfig) unmarshal(s *config.Subsection) {
 	c.Fetch = fetch
 }
 
-func (c *RemoteConfig) marshal() *config.Subsection {
+func (c *RemoteConfig) marshal() *format.Subsection {
 	if c.raw == nil {
-		c.raw = &config.Subsection{}
+		c.raw = &format.Subsection{}
 	}
 
 	c.raw.Name = c.Name
diff --git a/config/modules.go b/config/modules.go
index 6733884..8b3d2b8 100644
--- a/config/modules.go
+++ b/config/modules.go
@@ -4,7 +4,7 @@ import (
 	"bytes"
 	"errors"
 
-	"gopkg.in/src-d/go-git.v4/plumbing/format/config"
+	format "gopkg.in/src-d/go-git.v4/plumbing/format/config"
 )
 
 var (
@@ -12,18 +12,20 @@ var (
 	ErrModuleEmptyPath = errors.New("module config: empty path")
 )
 
-// Modules defines the submodules properties
+// Modules defines the submodules properties, represents a .gitmodules file
+// https://www.kernel.org/pub/software/scm/git/docs/gitmodules.html
 type Modules struct {
+	// Submodules is a map of submodules being the key the name of the submodule
 	Submodules map[string]*Submodule
 
-	raw *config.Config
+	raw *format.Config
 }
 
 // NewModules returns a new empty Modules
 func NewModules() *Modules {
 	return &Modules{
 		Submodules: make(map[string]*Submodule, 0),
-		raw:        config.New(),
+		raw:        format.New(),
 	}
 }
 
@@ -36,9 +38,9 @@ const (
 // Unmarshal parses a git-config file and stores it
 func (m *Modules) Unmarshal(b []byte) error {
 	r := bytes.NewBuffer(b)
-	d := config.NewDecoder(r)
+	d := format.NewDecoder(r)
 
-	m.raw = config.New()
+	m.raw = format.New()
 	if err := d.Decode(m.raw); err != nil {
 		return err
 	}
@@ -57,7 +59,7 @@ func (m *Modules) Unmarshal(b []byte) error {
 // Marshal returns Modules encoded as a git-config file
 func (m *Modules) Marshal() ([]byte, error) {
 	s := m.raw.Section(submoduleSection)
-	s.Subsections = make(config.Subsections, len(m.Submodules))
+	s.Subsections = make(format.Subsections, len(m.Submodules))
 
 	var i int
 	for _, r := range m.Submodules {
@@ -66,7 +68,7 @@ func (m *Modules) Marshal() ([]byte, error) {
 	}
 
 	buf := bytes.NewBuffer(nil)
-	if err := config.NewEncoder(buf).Encode(m.raw); err != nil {
+	if err := format.NewEncoder(buf).Encode(m.raw); err != nil {
 		return nil, err
 	}
 
@@ -74,7 +76,6 @@ func (m *Modules) Marshal() ([]byte, error) {
 }
 
 // Submodule defines a submodule
-// https://www.kernel.org/pub/software/scm/git/docs/gitmodules.html
 type Submodule struct {
 	// Name module name
 	Name string
@@ -84,10 +85,12 @@ type Submodule struct {
 	// URL defines a URL from which the submodule repository can be cloned.
 	URL string
 	// Branch is a remote branch name for tracking updates in the upstream
-	// submodule.
+	// submodule. Optional value.
 	Branch string
 
-	raw *config.Subsection
+	// raw representation of the subsection, filled by marshal or unmarshal are
+	// called
+	raw *format.Subsection
 }
 
 // Validate validate the fields and set the default values
@@ -103,7 +106,7 @@ func (m *Submodule) Validate() error {
 	return nil
 }
 
-func (m *Submodule) unmarshal(s *config.Subsection) {
+func (m *Submodule) unmarshal(s *format.Subsection) {
 	m.raw = s
 
 	m.Name = m.raw.Name
@@ -112,9 +115,9 @@ func (m *Submodule) unmarshal(s *config.Subsection) {
 	m.Branch = m.raw.Option(branchKey)
 }
 
-func (m *Submodule) marshal() *config.Subsection {
+func (m *Submodule) marshal() *format.Subsection {
 	if m.raw == nil {
-		m.raw = &config.Subsection{}
+		m.raw = &format.Subsection{}
 	}
 
 	m.raw.Name = m.Name
diff --git a/config/modules_test.go b/config/modules_test.go
index 34ad17c..ab7b116 100644
--- a/config/modules_test.go
+++ b/config/modules_test.go
@@ -69,5 +69,5 @@ func (s *ModulesSuite) TestUnmarshallMarshall(c *C) {
 
 	output, err := cfg.Marshal()
 	c.Assert(err, IsNil)
-	c.Assert(output, DeepEquals, input)
+	c.Assert(string(output), DeepEquals, string(input))
 }