From ff87377acf31d1fb5366838a71213a4503978357 Mon Sep 17 00:00:00 2001
From: Darien Raymond <admin@v2ray.com>
Date: Sun, 11 Dec 2016 09:43:20 +0100
Subject: [PATCH] comments

---
 common/buf/buffer.go      | 19 ++++++++-----------
 common/buf/buffer_pool.go | 18 +++++++++++++++---
 2 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/common/buf/buffer.go b/common/buf/buffer.go
index 35957f30..48c8ff6a 100644
--- a/common/buf/buffer.go
+++ b/common/buf/buffer.go
@@ -19,16 +19,6 @@ type Buffer struct {
 	end   int
 }
 
-// CreateBuffer creates a new Buffer object based on given container and parent pool.
-func CreateBuffer(container []byte, parent Pool) *Buffer {
-	b := new(Buffer)
-	b.v = container
-	b.pool = parent
-	b.start = 0
-	b.end = 0
-	return b
-}
-
 // Release recycles the buffer into an internal buffer pool.
 func (b *Buffer) Release() {
 	if b == nil || b.v == nil {
@@ -81,6 +71,7 @@ func (b *Buffer) Bytes() []byte {
 	return b.v[b.start:b.end]
 }
 
+// Reset resets the content of the Buffer with a supplier.
 func (b *Buffer) Reset(writer Supplier) error {
 	b.start = 0
 	nBytes, err := writer(b.v[b.start:])
@@ -99,6 +90,7 @@ func (b *Buffer) BytesRange(from, to int) []byte {
 	return b.v[b.start+from : b.start+to]
 }
 
+// BytesFrom returns a slice of this Buffer starting from the given position.
 func (b *Buffer) BytesFrom(from int) []byte {
 	if from < 0 {
 		from += b.Len()
@@ -106,6 +98,7 @@ func (b *Buffer) BytesFrom(from int) []byte {
 	return b.v[b.start+from : b.end]
 }
 
+// BytesFrom returns a slice of this Buffer from start to the given position.
 func (b *Buffer) BytesTo(to int) []byte {
 	if to < 0 {
 		to += b.Len()
@@ -175,6 +168,7 @@ func (b *Buffer) Read(data []byte) (int, error) {
 	return nBytes, nil
 }
 
+// String returns the string form of this Buffer.
 func (b *Buffer) String() string {
 	return string(b.Bytes())
 }
@@ -191,5 +185,8 @@ func NewSmall() *Buffer {
 
 // NewLocal creates and returns a buffer on current thread.
 func NewLocal(size int) *Buffer {
-	return CreateBuffer(make([]byte, size), nil)
+	return &Buffer{
+		v:    make([]byte, size),
+		pool: nil,
+	}
 }
diff --git a/common/buf/buffer_pool.go b/common/buf/buffer_pool.go
index 2d369f0c..f689bc8e 100644
--- a/common/buf/buffer_pool.go
+++ b/common/buf/buffer_pool.go
@@ -31,7 +31,10 @@ func NewSyncPool(bufferSize uint32) *SyncPool {
 
 // Allocate implements Pool.Allocate().
 func (p *SyncPool) Allocate() *Buffer {
-	return CreateBuffer(p.allocator.Get().([]byte), p)
+	return &Buffer{
+		v:    p.allocator.Get().([]byte),
+		pool: p,
+	}
 }
 
 // Free implements Pool.Free().
@@ -43,11 +46,13 @@ func (p *SyncPool) Free(buffer *Buffer) {
 	p.allocator.Put(rawBuffer)
 }
 
+// BufferPool is a Pool that utilizes an internal cache.
 type BufferPool struct {
 	chain     chan []byte
 	allocator *sync.Pool
 }
 
+// NewBufferPool creates a new BufferPool with given buffer size, and internal cache size.
 func NewBufferPool(bufferSize, poolSize uint32) *BufferPool {
 	pool := &BufferPool{
 		chain: make(chan []byte, poolSize),
@@ -61,6 +66,7 @@ func NewBufferPool(bufferSize, poolSize uint32) *BufferPool {
 	return pool
 }
 
+// Allocate implements Pool.Allocate().
 func (p *BufferPool) Allocate() *Buffer {
 	var b []byte
 	select {
@@ -68,9 +74,13 @@ func (p *BufferPool) Allocate() *Buffer {
 	default:
 		b = p.allocator.Get().([]byte)
 	}
-	return CreateBuffer(b, p)
+	return &Buffer{
+		v:    b,
+		pool: p,
+	}
 }
 
+// Free implements Pool.Free().
 func (p *BufferPool) Free(buffer *Buffer) {
 	rawBuffer := buffer.v
 	if rawBuffer == nil {
@@ -84,7 +94,9 @@ func (p *BufferPool) Free(buffer *Buffer) {
 }
 
 const (
-	Size      = 8 * 1024
+	// Size of a regular buffer.
+	Size = 8 * 1024
+	// Size of a small buffer.
 	SizeSmall = 2 * 1024
 
 	PoolSizeEnvKey = "v2ray.buffer.size"