Merge pull request #95 from hellofresh/feature/docs-improvements

improving godoc

README.md

@@ -4,7 +4,9 @@
 
 # Klepto
 
-[![](https://travis-ci.org/hellofresh/klepto.svg?branch=master)](https://travis-ci.org/hellofresh/klepto)
+[![Build Status](https://travis-ci.org/hellofresh/klepto.svg?branch=master)](https://travis-ci.org/hellofresh/klepto)
+[![Go Report Card](https://goreportcard.com/badge/github.com/hellofresh/klepto)](https://goreportcard.com/report/github.com/hellofresh/klepto)
+[![Go Doc](https://godoc.org/github.com/hellofresh/klepto?status.svg)](https://godoc.org/github.com/hellofresh/klepto)
 
 > Klepto is a tool for copying and anonymising data
 
@@ -121,8 +123,21 @@ We recommend to always set the following parameters:
 
 <a name="configuration-file-options"></a>
 ## Configuration File Options
-You can set a number of keys in the configuration file.
-
+You can set a number of keys in the configuration file. Here is the list of all configuration options:
+- `Matchers` are variables to store filter data, you can declare a filter once and reuse it among tables.
+- `Tables` represents a klepto table definition.
+  - `Name` is the table name.
+  - `IgnoreData` if set to true, it will dump the table structure without importing data.
+  - `Filter` represents the way you want to filter the results.
+    - `Match` is a condition field to dump only certain amount data.
+    - `Limit` defines a limit of results to be fetched.
+    - `Sorts` is the sort condition for the table.
+  - `Anonymise` anonymise columns.
+  - `Relationships` represents the relationship between the table and referenced table.
+    - `Table` is the table name.
+    - `ForeignKey` is the table name foreign key.
+    - `ReferencedTable` is the referenced table name.
+    - `ReferencedKey` is the referenced table primary key name.
 
 <a name="relationships"></a>
 ### Relationships

cmd/steal.go

@@ -18,8 +18,8 @@ import (
 	_ "github.com/hellofresh/klepto/pkg/reader/postgres"
 )
 
-// StealOptions represents the command options
 type (
+	// StealOptions represents the command options
 	StealOptions struct {
 		from        string
 		to          string

cmd/update.go

@@ -11,15 +11,16 @@ const (
 	githubRepo  = "klepto"
 )
 
-// UpdateOptions are the command flags
-type UpdateOptions struct {
-	token string
-}
+type (
+	// UpdateOptions are the command flags
+	UpdateOptions struct {
+		token string
+	}
+)
 
 // NewUpdateCmd creates a new update command
 func NewUpdateCmd() *cobra.Command {
-	opts := &UpdateOptions{}
-
+	opts := new(UpdateOptions)
 	cmd := &cobra.Command{
 		Use:   "update",
 		Short: "Check for new versions of kepto",

pkg/anonymiser/anonymiser.go

@@ -22,18 +22,19 @@ const (
 	password      = "Password"
 )
 
-// anonymiser is responsible for anonymising columns
-type anonymiser struct {
-	reader.Reader
-	tables config.Tables
-}
+type (
+	anonymiser struct {
+		reader.Reader
+		tables config.Tables
+	}
+)
 
-// NewAnonymiser returns an initialised instance of MySQLAnonymiser
+// NewAnonymiser returns a new anonymiser reader.
 func NewAnonymiser(source reader.Reader, tables config.Tables) reader.Reader {
 	return &anonymiser{source, tables}
 }
 
-// ReadTable wraps reader.ReadTable method for anonymising rows published from the reader.Reader
+// ReadTable decorates reader.ReadTable method for anonymising rows published from the reader.Reader
 func (a *anonymiser) ReadTable(tableName string, rowChan chan<- database.Row, opts reader.ReadTableOpt, matchers config.Matchers) error {
 	logger := log.WithField("table", tableName)
 	logger.Debug("Loading anonymiser config")

pkg/config/config.go

@@ -3,44 +3,57 @@ package config
 import "errors"
 
 type (
-	// Spec represents the global app configuration
+	// Spec represents the global app configuration.
 	Spec struct {
 		Matchers
 		Tables
 	}
 
-	// Matchers are variables to replace placeolders in filter
+	// Matchers are variables to store filter data,
+	// you can declare a filter once and reuse it among tables.
 	Matchers map[string]string
 
-	// Tables are an array of table
+	// Tables are an array of table definitions.
 	Tables []*Table
 
-	// Table represents a klepto table definition
+	// Table represents a klepto table definition.
 	Table struct {
-		Name          string
-		IgnoreData    bool
-		Filter        Filter
-		Anonymise     map[string]string
+		// Name is the table name.
+		Name string
+		// IgnoreData if set to true, it will dump the table structure without importing data.
+		IgnoreData bool
+		// Filter represents the way you want to filter the results.
+		Filter
+		// Anonymise anonymise columns.
+		Anonymise map[string]string
+		// Relationship is an collection of relationship definitions.
 		Relationships []*Relationship
 	}
 
-	// Filter represents the way you want to filter the results
+	// Filter represents the way you want to filter the results.
 	Filter struct {
+		// Match is a condition field to dump only certain amount data.
 		Match string
+		// Limit defines a limit of results to be fetched.
 		Limit uint64
+		// Sorts is the sort condition for the table.
 		Sorts map[string]string
 	}
 
-	// Relationship represents a relationship definition
+	// Relationship represents the relationship between the table and referenced table.
 	Relationship struct {
-		Table           string
-		ForeignKey      string
+		// Table is the table name.
+		Table string
+		// ForeignKey is the table name foreign key.
+		ForeignKey string
+		// ReferencedTable is the referenced table name.
 		ReferencedTable string
-		ReferencedKey   string
+		// ReferencedKey is the referenced table primary key name.
+		ReferencedKey string
 	}
 )
 
-// FindByName filter a table by its name
+// FindByName find a table by its name.
 func (t Tables) FindByName(name string) (*Table, error) {
 	for _, table := range t {
 		if table.Name == name {

pkg/database/database.go

@@ -1,5 +1,6 @@
 package database
 
 type (
+	// Row is the database column row.
 	Row map[string]interface{}
 )

pkg/dsn/dsn.go

@@ -14,6 +14,14 @@ var (
 	ErrEmptyDsn = errors.New("Empty string provided for dsn")
 	// ErrInvalidDsn defines error returned when the dsn is invalid
 	ErrInvalidDsn = errors.New("Invalid dsn")
+
+	// From https://github.com/go-sql-driver/mysql/blob/f4bf8e8e0aa93d4ead0c6473503ca2f5d5eb65a8/utils.go#L34
+	regex = regexp.MustCompile(
+		`^(?:(?P<Type>.*?)?://)?` + // [type://]
+			`(?:(?P<Username>.*?)(?::(?P<Password>.*))?@)?` + // [username[:password]@]
+			`(?:(?P<Protocol>[^\(]*)(?:\((?P<Address>[^\)]*)\))?)?` + // [protocol[(address)]]
+			`\/(?P<DataSource>.*?)` + // /datasource
+			`(?:\?(?P<Params>[^\?]*))?$`) // [?param1=value1]
 )
 
 // DSN describes how a DSN looks like
@@ -36,7 +44,7 @@ func Parse(s string) (*DSN, error) {
 		return nil, ErrEmptyDsn
 	}
 
-	dsn := &DSN{}
+	dsn := new(DSN)
 
 	matches := regex.FindStringSubmatch(s)
 	if len(matches) < 1 || len(matches) > 1 && matches[1] == "" {
@@ -74,17 +82,7 @@ func Parse(s string) (*DSN, error) {
 	return dsn, nil
 }
 
-var (
-	// From https://github.com/go-sql-driver/mysql/blob/f4bf8e8e0aa93d4ead0c6473503ca2f5d5eb65a8/utils.go#L34
-	regex = regexp.MustCompile(
-		`^(?:(?P<Type>.*?)?://)?` + // [type://]
-			`(?:(?P<Username>.*?)(?::(?P<Password>.*))?@)?` + // [username[:password]@]
-			`(?:(?P<Protocol>[^\(]*)(?:\((?P<Address>[^\)]*)\))?)?` + // [protocol[(address)]]
-			`\/(?P<DataSource>.*?)` + // /datasource
-			`(?:\?(?P<Params>[^\?]*))?$`) // [?param1=value1]
-)
-
-// Converts a DSN struct into its string representation.
+// String converts a DSN struct into its string representation.
 func (d DSN) String() string {
 	str := ""
 

pkg/dumper/dumper.go

@@ -12,24 +12,32 @@ import (
 type (
 	// Driver is a driver interface used to support multiple drivers
 	Driver interface {
+		// IsSupported checks if the given dsn connection string is supported.
 		IsSupported(dsn string) bool
+		// NewConnection creates a new database connection and retrieves a dumper implementation.
 		NewConnection(ConnOpts, reader.Reader) (Dumper, error)
 	}
 
 	// A Dumper writes a database's stucture to the provided stream.
 	Dumper interface {
+		// Dump executes the dump process.
 		Dump(chan<- struct{}, *config.Spec, int) error
 		// Close closes the dumper resources and releases them.
 		Close() error
 	}
 
 	// ConnOpts are the options to create a connection
 	ConnOpts struct {
-		DSN             string
-		Timeout         time.Duration
+		// DSN is the connection address.
+		DSN string
+		// Timeout is the timeout for dump operations.
+		Timeout time.Duration
+		// MaxConnLifetime is the maximum amount of time a connection may be reused on the read database.
 		MaxConnLifetime time.Duration
-		MaxConns        int
-		MaxIdleConns    int
+		// MaxConns is the maximum number of open connections to the target database.
+		MaxConns int
+		// MaxIdleConns is the maximum number of connections in the idle connection pool for the write database.
+		MaxIdleConns int
 	}
 )
 
@@ -40,7 +48,7 @@ func NewDumper(opts ConnOpts, rdr reader.Reader) (dumper Dumper, err error) {
 		if !ok || !driver.IsSupported(opts.DSN) {
 			return true
 		}
-		log.WithField("driver", key).Debug("Found driver")
+		log.WithField("driver", key).Debug("found driver")
 
 		dumper, err = driver.NewConnection(opts, rdr)
 		return false