Golint: unixfs main module

License: MIT
Signed-off-by: Hector Sanjuan <hector@protocol.ai>

unixfs/format.go → unixfs/unixfs.go

-// Package format implements a data format for files in the IPFS filesystem It
+// Package unixfs implements a data format for files in the IPFS filesystem It
 // is not the only format in ipfs, but it is the one that the filesystem
 // assumes
 package unixfs
@@ -6,11 +6,13 @@ package unixfs
 import (
 	"errors"
 
+	proto "gx/ipfs/QmZ4Qi3GaRbjcx28Sme5eMH7RQjGkt8wHxt2a65oLaeFEV/gogo-protobuf/proto"
+
 	dag "github.com/ipfs/go-ipfs/merkledag"
 	pb "github.com/ipfs/go-ipfs/unixfs/pb"
-	proto "gx/ipfs/QmZ4Qi3GaRbjcx28Sme5eMH7RQjGkt8wHxt2a65oLaeFEV/gogo-protobuf/proto"
 )
 
+// Shorthands for protobuffer types
 const (
 	TRaw       = pb.Data_Raw
 	TFile      = pb.Data_File
@@ -20,10 +22,14 @@ const (
 	THAMTShard = pb.Data_HAMTShard
 )
 
-var ErrMalformedFileFormat = errors.New("malformed data in file format")
-var ErrInvalidDirLocation = errors.New("found directory node in unexpected place")
-var ErrUnrecognizedType = errors.New("unrecognized node type")
+// Common errors
+var (
+	ErrMalformedFileFormat = errors.New("malformed data in file format")
+	ErrInvalidDirLocation  = errors.New("found directory node in unexpected place")
+	ErrUnrecognizedType    = errors.New("unrecognized node type")
+)
 
+// FromBytes unmarshals a byte slice as protobuf Data.
 func FromBytes(data []byte) (*pb.Data, error) {
 	pbdata := new(pb.Data)
 	err := proto.Unmarshal(data, pbdata)
@@ -33,6 +39,8 @@ func FromBytes(data []byte) (*pb.Data, error) {
 	return pbdata, nil
 }
 
+// FilePBData creates a protobuf File with the given
+// byte slice and returns the marshaled protobuf bytes representing it.
 func FilePBData(data []byte, totalsize uint64) []byte {
 	pbfile := new(pb.Data)
 	typ := pb.Data_File
@@ -98,6 +106,7 @@ func SymlinkData(path string) ([]byte, error) {
 	return out, nil
 }
 
+// UnwrapData unmarshals a protobuf messages and returns the contents.
 func UnwrapData(data []byte) ([]byte, error) {
 	pbdata := new(pb.Data)
 	err := proto.Unmarshal(data, pbdata)
@@ -107,6 +116,10 @@ func UnwrapData(data []byte) ([]byte, error) {
 	return pbdata.GetData(), nil
 }
 
+// DataSize returns the size of the contents in protobuf wrapped slice.
+// For raw data it simply provides the length of it. For Data_Files, it
+// will return the associated filesize. Note that Data_Directories will
+// return an error.
 func DataSize(data []byte) (uint64, error) {
 	pbdata := new(pb.Data)
 	err := proto.Unmarshal(data, pbdata)
@@ -116,16 +129,17 @@ func DataSize(data []byte) (uint64, error) {
 
 	switch pbdata.GetType() {
 	case pb.Data_Directory:
-		return 0, errors.New("Cant get data size of directory!")
+		return 0, errors.New("Cant get data size of directory")
 	case pb.Data_File:
 		return pbdata.GetFilesize(), nil
 	case pb.Data_Raw:
 		return uint64(len(pbdata.GetData())), nil
 	default:
-		return 0, errors.New("Unrecognized node data type!")
+		return 0, errors.New("Unrecognized node data type")
 	}
 }
 
+// An FSNode represents a filesystem object.
 type FSNode struct {
 	Data []byte
 
@@ -139,6 +153,7 @@ type FSNode struct {
 	Type pb.Data_DataType
 }
 
+// FSNodeFromBytes unmarshal a protobuf message onto an FSNode.
 func FSNodeFromBytes(b []byte) (*FSNode, error) {
 	pbn := new(pb.Data)
 	err := proto.Unmarshal(b, pbn)
@@ -160,11 +175,13 @@ func (n *FSNode) AddBlockSize(s uint64) {
 	n.blocksizes = append(n.blocksizes, s)
 }
 
+// RemoveBlockSize removes the given child block's size.
 func (n *FSNode) RemoveBlockSize(i int) {
 	n.subtotal -= n.blocksizes[i]
 	n.blocksizes = append(n.blocksizes[:i], n.blocksizes[i+1:]...)
 }
 
+// GetBytes marshals this node as a protobuf message.
 func (n *FSNode) GetBytes() ([]byte, error) {
 	pbn := new(pb.Data)
 	pbn.Type = &n.Type
@@ -180,16 +197,19 @@ func (n *FSNode) FileSize() uint64 {
 	return uint64(len(n.Data)) + n.subtotal
 }
 
+// NumChildren returns the number of child blocks of this node
 func (n *FSNode) NumChildren() int {
 	return len(n.blocksizes)
 }
 
+// Metadata is used to store additional FSNode information.
 type Metadata struct {
 	MimeType string
 	Size     uint64
 }
 
-//MetadataFromBytes Unmarshals a protobuf message into Metadata.
+// MetadataFromBytes Unmarshals a protobuf Data message into Metadata.
+// The provided slice should have been encoded with BytesForMetadata().
 func MetadataFromBytes(b []byte) (*Metadata, error) {
 	pbd := new(pb.Data)
 	err := proto.Unmarshal(b, pbd)
@@ -210,12 +230,16 @@ func MetadataFromBytes(b []byte) (*Metadata, error) {
 	return md, nil
 }
 
+// Bytes marshals Metadata as a protobuf message of Metadata type.
 func (m *Metadata) Bytes() ([]byte, error) {
 	pbm := new(pb.Metadata)
 	pbm.MimeType = &m.MimeType
 	return proto.Marshal(pbm)
 }
 
+// BytesForMetadata wraps the given Metadata as a profobuf message of Data type,
+// setting the DataType to Metadata. The wrapped bytes are itself the
+// result of calling m.Bytes().
 func BytesForMetadata(m *Metadata) ([]byte, error) {
 	pbd := new(pb.Data)
 	pbd.Filesize = proto.Uint64(m.Size)
@@ -230,6 +254,7 @@ func BytesForMetadata(m *Metadata) ([]byte, error) {
 	return proto.Marshal(pbd)
 }
 
+// EmptyDirNode creates an empty folder Protonode.
 func EmptyDirNode() *dag.ProtoNode {
 	return dag.NodeWithData(FolderPBData())
 }