coreapi unixfs: docs on options

License: MIT
Signed-off-by: Łukasz Magiera <magik6k@gmail.com>

core/coreapi/interface/options/unixfs.go

@@ -13,7 +13,7 @@ type Layout int
 
 const (
 	BalancedLayout Layout = iota
-	TrickleLeyout
+	TrickleLayout
 )
 
 type UnixfsAddSettings struct {
@@ -95,20 +95,27 @@ type unixfsOpts struct{}
 
 var Unixfs unixfsOpts
 
+// CidVersion specifies which CID version to use. Defaults to 0 unless an option
+// that depends on CIDv1 is passed.
 func (unixfsOpts) CidVersion(version int) UnixfsAddOption {
 	return func(settings *UnixfsAddSettings) error {
 		settings.CidVersion = version
 		return nil
 	}
 }
 
+// Hash function to use. Implies CIDv1 if not set to sha2-256 (default).
+//
+// Table of functions is declared in https://github.com/multiformats/go-multihash/blob/master/multihash.go
 func (unixfsOpts) Hash(mhtype uint64) UnixfsAddOption {
 	return func(settings *UnixfsAddSettings) error {
 		settings.MhType = mhtype
 		return nil
 	}
 }
 
+// RawLeaves specifies whether to use raw blocks for leaves (data nodes with no
+// links) instead of wrapping them with unixfs structures.
 func (unixfsOpts) RawLeaves(enable bool) UnixfsAddOption {
 	return func(settings *UnixfsAddSettings) error {
 		settings.RawLeaves = enable
@@ -117,41 +124,61 @@ func (unixfsOpts) RawLeaves(enable bool) UnixfsAddOption {
 	}
 }
 
+// InlineLimit sets the amount of bytes below which blocks will be encoded
+// directly into CID instead of being stored and addressed by it's hash
+//
+// Note that while there is no hard limit on the number of bytes here, it should
+// be kept at something reasonably low like 32b (default for 'ipfs add')
 func (unixfsOpts) InlineLimit(limit int) UnixfsAddOption {
 	return func(settings *UnixfsAddSettings) error {
 		settings.InlineLimit = limit
 		return nil
 	}
 }
 
+// Chunker specifies settings for the chunking algorithm to use.
+//
+// Default: size-262144, formats:
+// size-[bytes] - Simple chunker splitting data into blocks of n bytes
+// rabin-[min]-[avg]-[max] - Rabin chunker
 func (unixfsOpts) Chunker(chunker string) UnixfsAddOption {
 	return func(settings *UnixfsAddSettings) error {
 		settings.Chunker = chunker
 		return nil
 	}
 }
 
+// Layout tells the adder how to balance data between leaves.
+// options.BalancedLayout is the default, it's optimized for static seekable
+// files.
+// options.TrickleLayout is optimized for streaming data,
 func (unixfsOpts) Layout(layout Layout) UnixfsAddOption {
 	return func(settings *UnixfsAddSettings) error {
 		settings.Layout = layout
 		return nil
 	}
 }
 
+// Pin tells the adder to pin the file root recursively after adding
 func (unixfsOpts) Pin(pin bool) UnixfsAddOption {
 	return func(settings *UnixfsAddSettings) error {
 		settings.Pin = pin
 		return nil
 	}
 }
 
+// HashOnly will make the adder calculate data hash without storing it in the
+// blockstore or announcing it to the network
 func (unixfsOpts) HashOnly(hashOnly bool) UnixfsAddOption {
 	return func(settings *UnixfsAddSettings) error {
 		settings.OnlyHash = hashOnly
 		return nil
 	}
 }
 
+// Local will add the data to blockstore without announcing it to the network
+//
+// Note that this doesn't prevent other nodes from getting this data
 func (unixfsOpts) Local(local bool) UnixfsAddOption {
 	return func(settings *UnixfsAddSettings) error {
 		settings.Local = local

core/coreapi/unixfs.go

@@ -78,7 +78,7 @@ func (api *UnixfsAPI) Add(ctx context.Context, r io.ReadCloser, opts ...options.
 	switch settings.Layout {
 	case options.BalancedLayout:
 		// Default
-	case options.TrickleLeyout:
+	case options.TrickleLayout:
 		fileAdder.Trickle = true
 	default:
 		return nil, fmt.Errorf("unknown layout: %d", settings.Layout)

core/coreapi/unixfs_test.go

@@ -202,7 +202,7 @@ func TestAdd(t *testing.T) {
 			name: "addChunksTrickle",
 			data: strings.Repeat("aoeuidhtns", 200),
 			path: "/ipfs/QmNNhDGttafX3M1wKWixGre6PrLFGjnoPEDXjBYpTv93HP",
-			opts: []options.UnixfsAddOption{options.Unixfs.Chunker("size-4"), options.Unixfs.Layout(options.TrickleLeyout)},
+			opts: []options.UnixfsAddOption{options.Unixfs.Chunker("size-4"), options.Unixfs.Layout(options.TrickleLayout)},
 		},
 		// Local
 		{