More doc

common/alloc/buffer.go

@@ -4,12 +4,16 @@ import (
 	"time"
 )
 
+// Buffer is a recyclable allocation of a byte array. Buffer.Release() recycles
+// the buffer into an internal buffer pool, in order to recreate a buffer more
+// quickly.
 type Buffer struct {
 	head  []byte
 	pool  *bufferPool
 	Value []byte
 }
 
+// Release recycles the buffer into an internal buffer pool.
 func (b *Buffer) Release() {
 	b.pool.free(b)
 	b.head = nil
@@ -17,39 +21,48 @@ func (b *Buffer) Release() {
 	b.pool = nil
 }
 
+// Clear clears the content of the buffer, results an empty buffer with
+// Len() = 0.
 func (b *Buffer) Clear() *Buffer {
 	b.Value = b.head[:0]
 	return b
 }
 
+// AppendBytes appends one or more bytes to the end of the buffer.
 func (b *Buffer) AppendBytes(bytes ...byte) *Buffer {
 	b.Value = append(b.Value, bytes...)
 	return b
 }
 
+// Append appends a byte array to the end of the buffer.
 func (b *Buffer) Append(data []byte) *Buffer {
 	b.Value = append(b.Value, data...)
 	return b
 }
 
+// Slice cuts the buffer at the given position.
 func (b *Buffer) Slice(from, to int) *Buffer {
 	b.Value = b.Value[from:to]
 	return b
 }
 
+// SliceFrom cuts the buffer at the given position.
 func (b *Buffer) SliceFrom(from int) *Buffer {
 	b.Value = b.Value[from:]
 	return b
 }
 
+// Len returns the length of the buffer content.
 func (b *Buffer) Len() int {
 	return len(b.Value)
 }
 
+// IsFull returns true if the buffer has no more room to grow.
 func (b *Buffer) IsFull() bool {
 	return len(b.Value) == cap(b.Value)
 }
 
+// Write implements Write method in io.Writer.
 func (b *Buffer) Write(data []byte) (int, error) {
 	b.Append(data)
 	return len(data), nil
@@ -115,14 +128,17 @@ var smallPool = newBufferPool(1024, 16, 64)
 var mediumPool = newBufferPool(8*1024, 256, 2048)
 var largePool = newBufferPool(64*1024, 128, 1024)
 
+// NewSmallBuffer creates a Buffer with 1K bytes of arbitrary content.
 func NewSmallBuffer() *Buffer {
 	return smallPool.allocate()
 }
 
+// NewBuffer creates a Buffer with 8K bytes of arbitrary content.
 func NewBuffer() *Buffer {
 	return mediumPool.allocate()
 }
 
+// NewLargeBuffer creates a Buffer with 64K bytes of arbitrary content.
 func NewLargeBuffer() *Buffer {
 	return largePool.allocate()
 }

common/log/access.go

@@ -5,6 +5,7 @@ import (
 	"os"
 )
 
+// AccessStatus is the status of an access request from clients.
 type AccessStatus string
 
 const (
@@ -70,6 +71,7 @@ func newFileAccessLogger(path string) accessLogger {
 
 var accessLoggerInstance accessLogger = &noOpAccessLogger{}
 
+// InitAccessLogger initializes the access logger to write into the give file.
 func InitAccessLogger(file string) {
 	logger := newFileAccessLogger(file)
 	if logger != nil {
@@ -78,6 +80,7 @@ func InitAccessLogger(file string) {
 	}
 }
 
+// Access writes an access log.
 func Access(from, to string, status AccessStatus, reason string) {
 	accessLoggerInstance.Log(from, to, status, reason)
 }

common/net/packet.go

@@ -4,12 +4,14 @@ import (
 	"github.com/v2ray/v2ray-core/common/alloc"
 )
 
+// Packet is a network packet to be sent to destination.
 type Packet interface {
 	Destination() Destination
 	Chunk() *alloc.Buffer // First chunk of this commnunication
 	MoreChunks() bool
 }
 
+// NewPacket creates a new Packet with given destination and payload.
 func NewPacket(dest Destination, firstChunk *alloc.Buffer, moreChunks bool) Packet {
 	return &packetImpl{
 		dest:     dest,

common/net/transport.go

@@ -6,6 +6,8 @@ import (
 	"github.com/v2ray/v2ray-core/common/alloc"
 )
 
+// ReadFrom reads from a reader and put all content to a buffer.
+// If buffer is nil, ReadFrom creates a new normal buffer.
 func ReadFrom(reader io.Reader, buffer *alloc.Buffer) (*alloc.Buffer, error) {
 	if buffer == nil {
 		buffer = alloc.NewBuffer()