Add English comments

README.md

@@ -1,2 +1,12 @@
 # picop-go
-PiCoP Implementation for Go
+PiCoP Protocol Library for Go
+
+## Description
+This repository provide Go library for communicating with PiCoP Protocol.
+
+## Support
+- `net`([`protocol/net`](./protocol/net`))
+- `net/http`([`contrib/net/http/picophttp`](./contrib/net/http/picophttp))
+- `github.com/go-sql-driver/mysql`([`contrib/github.com/go-sql-griver/mysql/picopmysql`](./contrib/github.com/go-sql-driver/mysql/picopmysql))
+
+You can refer to [`example`](./example) directory for usage.

contrib/github.com/go-sql-driver/mysql/picopmysql/dial.go

@@ -11,14 +11,12 @@ import (
 	otelprop "go.opentelemetry.io/otel/propagation"
 )
 
-//TODO: propagatorが固定できる場合はinit()でRegisterDialContext("tcp", propagator)する
-
 func RegisterDialContext(netP string, propagator otelprop.TextMapPropagator) {
 	mysql.RegisterDialContext(netP, DialContext(netP, propagator))
 }
 
 func DialContext(netP string, propagator otelprop.TextMapPropagator) mysql.DialContextFunc {
-	// connector.Connectで呼び出される
+	// This func is called by connector.Connect
 	// https://github.com/go-sql-driver/mysql/blob/4591e42e65cf483147a7c7a4f4cfeac81b21c917/connector.go#L37
 	return func(ctx context.Context, addr string) (net.Conn, error) {
 		nd := net.Dialer{}

contrib/net/http/picophttp/transport.go

@@ -29,7 +29,7 @@ func NewTransport(base *http.Transport, propagator otelprop.TextMapPropagator) T
 	t.DialContext = wrapDialContext(base.DialContext, propagator)
 	t.DialTLSContext = wrapDialContext(base.DialTLSContext, propagator)
 
-	// 異なるヘッダのリクエスト同士が同じコネクション使ってはいけない
+	// Requests with different headers must not use the same connection.
 	t.DisableKeepAlives = true
 	return t
 }

example/http-client/main.go

@@ -16,7 +16,7 @@ import (
 func main() {
 	port := flag.String("port", "8080", "request port")
 	flag.Parse()
-	// 伝播されたContextを用意
+	// Prepare propagated context
 	h := header.NewV1()
 	h.Set(propagation.EnvIDHeader, "aaaaa")
 	ctx := propagation.EnvID{}.Extract(context.Background(), propagation.NewPiCoPCarrier(h))

example/http-server/main.go

@@ -37,7 +37,7 @@ func main() {
 }
 
 func handler(w http.ResponseWriter, r *http.Request) {
-	// 伝播されたContextを確認
+	// Confirm propagated context
 	h := header.NewV1()
 	propagation.EnvID{}.Inject(r.Context(), propagation.NewPiCoPCarrier(h))
 	w.WriteHeader(http.StatusOK)

example/mysql-client/main.go

@@ -6,14 +6,14 @@ import (
 	"fmt"
 	"log"
 
-	// _ "github.com/go-sql-driver/mysql" picopmysql内でimportされるので不要
+	// _ "github.com/go-sql-driver/mysql" // Not required because it is imported by picopmysql
 	"github.com/picop-rd/picop-go/contrib/github.com/go-sql-driver/mysql/picopmysql"
 	"github.com/picop-rd/picop-go/propagation"
 	"github.com/picop-rd/picop-go/protocol/header"
 )
 
 func main() {
-	// 伝播されたContextを用意
+	// Prepare propagated context
 	h := header.NewV1()
 	h.Set(propagation.EnvIDHeader, "aaaaa")
 	ctx := propagation.EnvID{}.Extract(context.Background(), propagation.NewPiCoPCarrier(h))
@@ -25,7 +25,7 @@ func main() {
 		log.Fatal(err)
 	}
 	defer db.Close()
-	db.SetMaxIdleConns(0)
+	db.SetMaxIdleConns(0) // Requests with different headers must not use the same connection.
 
 	_, err = db.ExecContext(ctx, "INSERT INTO books(id, name) VALUES (1, \"test1\")")
 	if err != nil {

example/tcp-client/main.go

@@ -27,6 +27,7 @@ func main() {
 	}
 	defer conn.Close()
 
+	// Prepare propagated context
 	h := header.NewV1()
 	h.Set(propagation.EnvIDHeader, "aaaaa")
 	bconn := picopnet.SenderConn(conn, h)

example/tcp-server/main.go

@@ -30,6 +30,7 @@ func main() {
 	}
 	defer bconn.Close()
 
+	// Confirm propagated context
 	header, err := bconn.ReadHeader()
 	if err != nil {
 		log.Fatal(err)

protocol/header/header_test.go

@@ -17,27 +17,27 @@ func TestParse(t *testing.T) {
 		wantErr   bool
 	}{
 		{
-			name:      "headerのみを正常に受理できる",
+			name:      "It can accept only a header.",
 			input:     makeV1HeaderByte(11, "key1:value1"),
 			wantValue: makeV1HeaderStruct("key1", "value1"),
 		},
 		{
-			name:      "header+追加データを正常に受理できる",
+			name:      "It can accept a header and additional data.",
 			input:     makeV1HeaderByte(11, "key1:value1testtest"),
 			wantValue: makeV1HeaderStruct("key1", "value1"),
 		},
 		{
-			name:      "複数headerを正常に受理できる",
+			name:      "It can accept headers.",
 			input:     makeV1HeaderByte(39, "key1:value1\r\nkey2:value21\r\nkey2:value22"),
 			wantValue: makeV1HeaderStruct("key1", "value1", "key2", "value21", "key2", "value22"),
 		},
 		{
-			name:      "valueが\"\"でも正常に受理できる",
+			name:      "It can accept an empty value",
 			input:     makeV1HeaderByte(5, "key1:"),
 			wantValue: makeV1HeaderStruct("key1", ""),
 		},
 		{
-			name:      "valueに:があるとエラー",
+			name:      "It can raise an error if the value has :",
 			input:     makeV1HeaderByte(11, "key1:va:ue1"),
 			wantValue: nil,
 			wantErr:   true,
@@ -69,12 +69,12 @@ func TestHeader_Format(t *testing.T) {
 		want  []byte
 	}{
 		{
-			name:  "正しくヘッダをフォーマットできる",
+			name:  "It can format a header.",
 			value: makeV1HeaderStruct("key1", "value1"),
 			want:  makeV1HeaderByte(11, "Key1:value1"),
 		},
 		{
-			name:  "正しく複数ヘッダをフォーマットできる",
+			name:  "It can format headers.",
 			value: makeV1HeaderStruct("key1", "value1", "key2", "value21", "key2", "value22"),
 			want:  makeV1HeaderByte(39, "Key1:value1\r\nKey2:value21\r\nKey2:value22"),
 		},

protocol/header/value.go

@@ -33,7 +33,7 @@ func (h MIMEHeader) String() string {
 	if len(ret) <= 1 {
 		return ""
 	}
-	return strings.Join(ret[:len(ret)-1], "") // 最後の\r\nを削除
+	return strings.Join(ret[:len(ret)-1], "") // Delete last \r\n
 }
 
 func parseMIMEHeader(data string) (MIMEHeader, error) {

protocol/header/value_test.go

@@ -14,12 +14,12 @@ func TestMIMEHeader_String(t *testing.T) {
 		want   string
 	}{
 		{
-			name:   "正しくフォーマットできる",
+			name:   "It can format a header.",
 			header: makeMIMEHeader("key1", "value1"),
 			want:   "Key1:value1",
 		},
 		{
-			name:   "正しく複数ヘッダをフォーマットできる",
+			name:   "It can format headers.",
 			header: makeMIMEHeader("key1", "value1", "key2", "value21", "key2", "value22"),
 			want:   "Key1:value1\r\nKey2:value21\r\nKey2:value22",
 		},