more doc

common/alloc/buffer.go

@@ -6,7 +6,7 @@ import (
 )
 
 const (
-	DefaultOffset = 16
+	defaultOffset = 16
 )
 
 // Buffer is a recyclable allocation of a byte array. Buffer.Release() recycles
@@ -33,7 +33,7 @@ func (b *Buffer) Release() {
 // Clear clears the content of the buffer, results an empty buffer with
 // Len() = 0.
 func (b *Buffer) Clear() *Buffer {
-	b.offset = DefaultOffset
+	b.offset = defaultOffset
 	b.Value = b.head[b.offset:b.offset]
 	return b
 }
@@ -58,6 +58,7 @@ func (b *Buffer) Prepend(data []byte) *Buffer {
 	return b
 }
 
+// Bytes returns the content bytes of this Buffer.
 func (b *Buffer) Bytes() []byte {
 	return b.Value
 }
@@ -74,6 +75,8 @@ func (b *Buffer) SliceFrom(from int) *Buffer {
 	return b
 }
 
+// SliceBack extends the Buffer to its front by offset bytes.
+// Caller must ensure cumulated offset is no more than 16.
 func (b *Buffer) SliceBack(offset int) *Buffer {
 	newoffset := b.offset - offset
 	if newoffset < 0 {
@@ -103,6 +106,7 @@ func (b *Buffer) Write(data []byte) (int, error) {
 	return len(data), nil
 }
 
+// Read implements io.Reader.Read().
 func (b *Buffer) Read(data []byte) (int, error) {
 	if b.Len() == 0 {
 		return 0, io.EOF
@@ -144,8 +148,8 @@ func (p *bufferPool) allocate() *Buffer {
 	return &Buffer{
 		head:   b,
 		pool:   p,
-		Value:  b[DefaultOffset:],
-		offset: DefaultOffset,
+		Value:  b[defaultOffset:],
+		offset: defaultOffset,
 	}
 }
 

common/common.go

@@ -1,4 +1,3 @@
 // Package common contains common utilities that are shared among other packages.
 // See each sub-package for detail.
-
 package common

common/io/reader.go

@@ -17,16 +17,20 @@ func ReadFrom(reader io.Reader, buffer *alloc.Buffer) (*alloc.Buffer, error) {
 	return buffer, err
 }
 
+// Reader extends io.Reader with alloc.Buffer.
 type Reader interface {
+	// Read reads content from underlying reader, and put it into an alloc.Buffer.
 	Read() (*alloc.Buffer, error)
 }
 
+// AdaptiveReader is a Reader that adjusts its reading speed automatically.
 type AdaptiveReader struct {
 	reader   io.Reader
 	allocate func() *alloc.Buffer
 	isLarge  bool
 }
 
+// NewAdaptiveReader creates a new AdaptiveReader.
 func NewAdaptiveReader(reader io.Reader) *AdaptiveReader {
 	return &AdaptiveReader{
 		reader:   reader,
@@ -35,6 +39,7 @@ func NewAdaptiveReader(reader io.Reader) *AdaptiveReader {
 	}
 }
 
+// Read implements Reader.Read().
 func (this *AdaptiveReader) Read() (*alloc.Buffer, error) {
 	buffer, err := ReadFrom(this.reader, this.allocate())
 

common/io/writer.go

@@ -6,20 +6,25 @@ import (
 	"github.com/v2ray/v2ray-core/common/alloc"
 )
 
+// Writer extends io.Writer with alloc.Buffer.
 type Writer interface {
+	// Write writes an alloc.Buffer into underlying writer.
 	Write(*alloc.Buffer) error
 }
 
+// AdaptiveWriter is a Writer that writes alloc.Buffer into underlying writer.
 type AdaptiveWriter struct {
 	writer io.Writer
 }
 
+// NewAdaptiveWriter creates a new AdaptiveWriter.
 func NewAdaptiveWriter(writer io.Writer) *AdaptiveWriter {
 	return &AdaptiveWriter{
 		writer: writer,
 	}
 }
 
+// Write implements Writer.Write().
 func (this *AdaptiveWriter) Write(buffer *alloc.Buffer) error {
 	nBytes, err := this.writer.Write(buffer.Value)
 	if nBytes < buffer.Len() {