Add more comments for public types. (#6)

Signed-off-by: NDoMyJob <46307927+DoMyJob@users.noreply.github.com>

cache/cachemanager.go

+// Package cache provides cache support used throughout YottaDisk.
 package cache
 
 import (
@@ -9,6 +10,7 @@ import (
 	"github.com/yottachain/YTFS/errors"
 )
 
+// CacheManager the entry point of LRU cache used by YottaDisk
 type CacheManager struct {
 	// Size
 	caps		uint64
@@ -27,6 +29,8 @@ type CacheManager struct {
 
 const logCache = false
 
+// NewCacheManager creates a new CacheManager, reports ErrConfigCache
+// if open failed.
 func NewCacheManager(itemSize uint32, cacheCaps uint64, onEvicted func(key interface{}, value interface{})) (*CacheManager, error) {
 	if cacheCaps < (uint64)(itemSize) {
 		cacheCaps = (uint64)(itemSize)
@@ -61,6 +65,7 @@ func NewCacheManager(itemSize uint32, cacheCaps uint64, onEvicted func(key inter
 	}, nil
 }
 
+// Add wraps the LRU cache Add() which adds a new cache item.
 func (cm *CacheManager) Add(key, value interface{}) bool {
 	if logCache {
 		fmt.Printf("Cache Add <%v:%v>\n", key, value)
@@ -68,6 +73,7 @@ func (cm *CacheManager) Add(key, value interface{}) bool {
 	return cm.Cache.Add(key, value)
 }
 
+// Contains wraps the LRU cache Contains() which check if a cache item exists.
 func (cm *CacheManager) Contains(key interface{}) bool {
 	if logCache {
 		fmt.Printf("Check if <%v> contains.\n", key)

common/header.go

+// Package common provides common types used throughout YottaDisk.
 package common
 
 // Header header of storage

errors/errors.go

+// Package errors provides common error types used throughout YottaDisk.
 package errors
 
 import (

opt/options.go

+// Package opt provides sets of options used by YottaDisk.
 package opt
 
 import (
@@ -12,30 +13,32 @@ import (
 	yotta "github.com/yottachain/YTFS/common"
 )
 
+// common size limitations
 const (
-	MAX_DISK_CAPABILITY	= 1 << 44 // 16T
-	MAX_RANGE_COVERAGE	= 1 << 16 // 64K
-	MAX_RANGE_NUMBER	= 1 << 16 // 64K
+	MaxDiskCapability = 1 << 44 // 16T
+	MaxRangeCoverage  = 1 << 16 // 64K
+	MaxRangeNumber    = 1 << 16 // 64K
 )
 
+// config errors
 var (
 	ErrConfigN          = errors.New("yotta config: config.N should be power of 2 and less than MAX_RANGE")
 	ErrConfigM          = errors.New("yotta config: config.M setting is incorrect")
-	ErrConfigMetaPeriod	= errors.New("yotta config: Meta sync period should be power of 2")
+	ErrConfigMetaPeriod = errors.New("yotta config: Meta sync period should be power of 2")
 )
 
 // Options Config options
 type Options struct {
-	StorageName		string				`json:"storage"`
-	StorageType 	yotta.StorageType	`json:"type"`
-	ReadOnly		bool				`json:"readonly"`
-	Sync			bool				`json:"writesync"`
-	MetaSyncPeriod	uint32				`json:"metadatasync"`
-	CacheSize		uint64				`json:"cache"`
-	M 				uint32 				`json:"M"`
-	N 				uint32 				`json:"N"`
-	T 				uint64 				`json:"T"`
-	D 				uint32 				`json:"D"`
+	StorageName    string            `json:"storage"`
+	StorageType    yotta.StorageType `json:"type"`
+	ReadOnly       bool              `json:"readonly"`
+	Sync           bool              `json:"writesync"`
+	MetaSyncPeriod uint32            `json:"metadatasync"`
+	CacheSize      uint64            `json:"cache"`
+	M              uint32            `json:"M"`
+	N              uint32            `json:"N"`
+	T              uint64            `json:"T"`
+	D              uint32            `json:"D"`
 }
 
 // DefaultOptions default config
@@ -46,16 +49,16 @@ func DefaultOptions() *Options {
 	}
 
 	config := &Options{
-		StorageName: tmpFile.Name(),
-		StorageType: yotta.FileStorageType,
-		ReadOnly: false,
-		Sync: true,
-		MetaSyncPeriod: 0,	// write meta every ${MetaSyncPeriod} data arrives. set to 0 if not sync with data write.
-		CacheSize: 0,		// Size cache in byte. Can be 0 which means only 1 L1(Range) table entry will be kepted.
-		M: 0,
-		N: 128,
-		T: 1 << 20,  	// 1M for default
-		D: 32,  		// Just save HashLen for test.
+		StorageName:    tmpFile.Name(),
+		StorageType:    yotta.FileStorageType,
+		ReadOnly:       false,
+		Sync:           true,
+		MetaSyncPeriod: 0, // write meta every ${MetaSyncPeriod} data arrives. set to 0 if not sync with data write.
+		CacheSize:      0, // Size cache in byte. Can be 0 which means only 1 L1(Range) table entry will be kepted.
+		M:              0,
+		N:              128,
+		T:              1 << 20, // 1M for default
+		D:              32,      // Just save HashLen for test.
 	}
 
 	newConfig, err := FinalizeConfig(config)
@@ -66,6 +69,7 @@ func DefaultOptions() *Options {
 	return newConfig
 }
 
+// ParseConfig parses a json config file and return a valid *Options
 func ParseConfig(fileName string) (*Options, error) {
 	dat, err := ioutil.ReadFile(fileName)
 	if err != nil {
@@ -86,6 +90,7 @@ func ParseConfig(fileName string) (*Options, error) {
 	return newConfig, nil
 }
 
+// SaveConfig saves config to file.
 func SaveConfig(config *Options, fileName string) error {
 	file, err := os.Create(fileName)
 	if err != nil {
@@ -102,9 +107,12 @@ func SaveConfig(config *Options, fileName string) error {
 	return nil
 }
 
+// FinalizeConfig finalize the config, it does following things:
+// 1. Do a few calculation according to config setting.
+// 2. Check if config setting is valid.
 func FinalizeConfig(config *Options) (*Options, error) {
-	if (config.T > MAX_DISK_CAPABILITY) {
-		return nil, errors.New("opt.N > MAX_DISK_CAPABILITY")
+	if config.T > MaxDiskCapability {
+		return nil, errors.New("opt.N > MaxDiskCapability")
 	}
 
 	t, d, n, m, h := config.T, (uint64)(config.D), (uint64)(config.N), (uint64)(config.M), (uint64)(unsafe.Sizeof(yotta.Header{}))
@@ -119,22 +127,22 @@ func FinalizeConfig(config *Options) (*Options, error) {
 	// --------+-------------------+-----------------------------+------------+----------------+
 	// h       + rangeLenSize * n  + indexTableEntrySize* n * m  + n * d * m  + (m * n + 7)/ 8 = t
 	// --------+-------------------+-----------------------------+------------+----------------+
-	m = ((t - h - rangeLenSize * n) * 8 - 7) / (indexTableEntrySize * n * 8 + n * d * 8 + n)
-	if m < 4 || m >= MAX_RANGE_COVERAGE {
+	m = ((t-h-rangeLenSize*n)*8 - 7) / (indexTableEntrySize*n*8 + n*d*8 + n)
+	if m < 4 || m >= MaxRangeCoverage {
 		// m can not == MAX_RANGE_COVERAGE because max uint16 is (MAX_RANGE_COVERAGE - 1)
 		// otherwise we shoud keep +1 in mind when calc the index table size, which seems a little bit tricky.
 		return nil, ErrConfigM
 	}
 	config.M = (uint32)(m)
 
-	if (config.N > MAX_RANGE_NUMBER && !yotta.IsPowerOfTwo((uint64)(config.N))) {
+	if config.N > MaxRangeNumber && !yotta.IsPowerOfTwo((uint64)(config.N)) {
 		return nil, ErrConfigN
 	}
 
-	if (config.MetaSyncPeriod != 0 && !yotta.IsPowerOfTwo((uint64)(config.MetaSyncPeriod))) {
+	if config.MetaSyncPeriod != 0 && !yotta.IsPowerOfTwo((uint64)(config.MetaSyncPeriod)) {
 		return nil, ErrConfigMetaPeriod
 	}
 
 	// TODO: return new object.
 	return config, nil
-}
\ No newline at end of file
+}

storage/storage.go

+// Package storage provides different storage types used throughout YottaDisk.
 package storage
 
 import (

yottadisk.go

@@ -20,11 +20,13 @@ import (
 	"github.com/yottachain/YTFS/cache"
 )
 
+// HashRangeIndex level 1 index size.
 type HashRangeIndex struct {
 	total	uint32			// total data saved.
 	sizes	[]uint16		// data len of each table.
 }
 
+// YottaDisk main entry of YTFS
 type YottaDisk struct {
 	config		*opt.Options
 	meta		ydcommon.Header
@@ -34,6 +36,7 @@ type YottaDisk struct {
 	sync.Mutex
 }
 
+// Close closes the YottaDisk.
 func (disk *YottaDisk) Close() {
 	if !disk.config.ReadOnly {
 		disk.flushMetaAndHashRegion()
@@ -41,6 +44,12 @@ func (disk *YottaDisk) Close() {
 	disk.store.Close()
 }
 
+// Get gets the value for the given key. It returns ErrNotFound if the
+// DB does not contains the key.
+//
+// The returned slice is its own copy, it is safe to modify the contents
+// of the returned slice.
+// It is safe to modify the contents of the argument after Get returns.
 func (disk *YottaDisk) Get(key ydcommon.IndexTableKey) ([]byte, error) {
 	disk.Lock()
 	defer disk.Unlock()
@@ -161,6 +170,10 @@ func (disk *YottaDisk) writeData(idx uint32, key ydcommon.IndexTableKey, dataOff
 	return nil
 }
 
+// Put sets the value for the given key. It panic if there exists any previous value
+// for that key; YottaDisk is not a multi-map.
+// It is safe to modify the contents of the arguments after Put returns but not
+// before.
 func (disk *YottaDisk) Put(key ydcommon.IndexTableKey, buf []byte) error {
 	if disk.config.ReadOnly {
 		return ErrReadOnly
@@ -227,6 +240,13 @@ func (disk *YottaDisk) flushMetaAndHashRegion() error {
 	return nil
 }
 
+// OpenYottaDisk opens or creates a YottaDisk for the given storage.
+// The DB will be created if not exist, unless Error happens.
+//
+// OpenYottaDisk will return ErrConfigXXX if config is incorrect.
+//
+// The returned YottaDisk instance is safe for concurrent use.
+// The YottaDisk must be closed after use, by calling Close method.
 func OpenYottaDisk(config *opt.Options) (*YottaDisk, error) {
 	if !ydcommon.IsPowerOfTwo((uint64)(config.N)) {
 		return nil, opt.ErrConfigN
@@ -454,12 +474,16 @@ func (disk *YottaDisk) loadTableFromStorage(idx uint32) ydcommon.IndexTable {
 	return table
 }
 
+// FormatYottaDisk formats an existed YottaDisk, and make it ready
+// for next put/get operation. so far we do quick format which just
+// erases the header.
 func (disk *YottaDisk) FormatYottaDisk() error {
 	// TODO: implement fully format, so far we just break the header
 	disk.meta = ydcommon.Header{}
 	return nil
 }
 
+// Meta reports meta info of this YottaDisk.
 func (disk *YottaDisk) Meta() *ydcommon.Header {
 	return &disk.meta
 }