Update docs

README.md

@@ -50,9 +50,9 @@ just like feature contributions.
 
 Modified copy of [go-sql-driver/mysql](https://github.com/go-sql-driver/mysql)
 is included with this project. It was changed in order to expose certain low
-level functions that are used to establish a slave connection and to remove
-automatic driver registration because it will likely conflict with the original
-code when imported as a dependency.
+level functions that allow to establish a connection manually and register as a
+replica server and to remove automatic driver registration because it will
+likely conflict with the original code when imported as a dependency.
 
 ### Licence
 

go.mod

@@ -5,3 +5,5 @@ require (
 	github.com/google/go-cmp v0.3.1
 	github.com/juju/errors v0.0.0-20190930114154-d42613fe1ab9
 )
+
+go 1.13

mysql/driver/conn.go

@@ -9,18 +9,24 @@ import (
 	"github.com/localhots/bocadillo/mysql/driver/internal/mysql"
 )
 
-// Conn is a slave connection used to issue a binlog dump command.
+// Conn is a connection used to issue a binlog dump command.
 type Conn struct {
 	conn *mysql.ExtendedConn
 	conf Config
 }
 
-// Config contains slave connection configuration. It is passed to master upon
-// registration.
+// Config contains all the details necessary to establish a replica connection.
 type Config struct {
-	ServerID uint32
+	// File and offset describe current state.
+	// File is the name of the binary log file.
 	File string
+	// Offset is the binary offset of the first event in the binary log file,
+	// a starting point at which processing should begin.
 	Offset uint32
+	// ServerID should be a unique replica server identifier (i guess).
+	ServerID uint32
+	// Hostname along with server ID is used to identify the replica server
+	// connection.
 	Hostname string
 }
 
@@ -29,13 +35,16 @@ const (
 	comRegisterSlave byte = 21
 	comBinlogDump    byte = 18
 
-	// Bytes
+	// Result codes
 	resultOK  byte = 0x00
 	resultEOF byte = 0xFE
 	resultERR byte = 0xFF
 )
 
-// Connect esablishes a new slave connection.
+// Connect esablishes a new database connection. It is a go-sql-driver
+// connection with a few low level functions exposed and with a high level
+// wrapper that allows to execute just a few commands that are required for
+// operation.
 func Connect(dsn string, conf Config) (*Conn, error) {
 	if conf.Hostname == "" {
 		name, err := os.Hostname()
@@ -62,8 +71,7 @@ func Connect(dsn string, conf Config) (*Conn, error) {
 	return &Conn{conn: extconn, conf: conf}, nil
 }
 
-// ReadPacket reads next packet from the server and processes the first status
-// byte.
+// ReadPacket reads next packet from the server and peeks at the status byte.
 func (c *Conn) ReadPacket(ctx context.Context) ([]byte, error) {
 	data, err := c.conn.ReadPacket(ctx)
 	if err != nil {

mysql/driver/internal/mysql/bocadillo_api.go

@@ -36,7 +36,7 @@ func (c *ExtendedConn) Exec(query string) error {
 	return c.exec(query)
 }
 
-// ReadPacket reads a packet from a given connection.
+// ReadPacket reads a packet from the connection.
 func (c *ExtendedConn) ReadPacket(ctx context.Context) ([]byte, error) {
 	if dl, ok := ctx.Deadline(); ok {
 		dur := dl.Sub(time.Now())
@@ -51,7 +51,7 @@ func (c *ExtendedConn) ReadPacket(ctx context.Context) ([]byte, error) {
 	return c.readPacket()
 }
 
-// WritePacket writes a packet to a given connection.
+// WritePacket writes a packet to the connection.
 func (c *ExtendedConn) WritePacket(p []byte) error {
 	return c.writePacket(p)
 }

reader/reader.go

@@ -37,7 +37,7 @@ var (
 func New(dsn string, sc driver.Config) (*Reader, error) {
 	conn, err := driver.Connect(dsn, sc)
 	if err != nil {
-		return nil, errors.Annotate(err, "establish slave connection")
+		return nil, errors.Annotate(err, "establish connection")
 	}
 
 	r := &Reader{
@@ -53,7 +53,7 @@ func New(dsn string, sc driver.Config) (*Reader, error) {
 		return nil, errors.Annotate(err, "disable binlog checksum")
 	}
 	if err := conn.RegisterSlave(); err != nil {
-		return nil, errors.Annotate(err, "register slave server")
+		return nil, errors.Annotate(err, "register replica server")
 	}
 	if err := conn.StartBinlogDump(); err != nil {
 		return nil, errors.Annotate(err, "start binlog dump")