docs: Add comments for each data types. (#1881)

object-datatypes.go

@@ -20,96 +20,202 @@ import "time"
 
 // StorageInfo - represents total capacity of underlying storage.
 type StorageInfo struct {
-	Total int64 // Total disk space.
+	// Total disk space.
-	Free  int64 // Free total available disk space.
+	Total int64
+	// Free available disk space.
+	Free int64
 }
 
-// BucketInfo - bucket name and create date
+// BucketInfo - represents bucket metadata.
 type BucketInfo struct {
-	Name    string
+	// Name of the bucket.
+	Name string
+
+	// Date and time when the bucket was created.
 	Created time.Time
 }
 
-// ObjectInfo - object info.
+// ObjectInfo - represents object metadata.
 type ObjectInfo struct {
-	Bucket          string
+	// Name of the bucket.
-	Name            string
+	Bucket string
-	ModTime         time.Time
+
-	Size            int64
+	// Name of the object.
-	IsDir           bool
+	Name string
-	MD5Sum          string
+
-	ContentType     string
+	// Date and time when the object was last modified.
+	ModTime time.Time
+
+	// Total object size.
+	Size int64
+
+	// IsDir indicates if the object is prefix.
+	IsDir bool
+
+	// Hex encoded md5 checksum of the object.
+	MD5Sum string
+
+	// A standard MIME type describing the format of the object.
+	ContentType string
+
+	// Specifies what content encodings have been applied to the object and thus
+	// what decoding mechanisms must be applied to obtain the object referenced
+	// by the Content-Type header field.
 	ContentEncoding string
 }
 
-// ListPartsInfo - various types of object resources.
+// ListPartsInfo - represents list of all parts.
 type ListPartsInfo struct {
-	Bucket               string
+	// Name of the bucket.
-	Object               string
+	Bucket string
-	UploadID             string
-	StorageClass         string
-	PartNumberMarker     int
-	NextPartNumberMarker int
-	MaxParts             int
-	IsTruncated          bool
 
-	Parts        []partInfo
+	// Name of the object.
-	EncodingType string
+	Object string
+
+	// Upload ID identifying the multipart upload whose parts are being listed.
+	UploadID string
+
+	// The class of storage used to store the object.
+	StorageClass string
+
+	// Part number after which listing begins.
+	PartNumberMarker int
+
+	// When a list is truncated, this element specifies the last part in the list,
+	// as well as the value to use for the part-number-marker request parameter
+	// in a subsequent request.
+	NextPartNumberMarker int
+
+	// Maximum number of parts that were allowed in the response.
+	MaxParts int
+
+	// Indicates whether the returned list of parts is truncated.
+	IsTruncated bool
+
+	// List of all parts.
+	Parts []partInfo
+
+	EncodingType string // Not supported yet.
 }
 
-// ListMultipartsInfo - various types of bucket resources for inprogress multipart uploads.
+// ListMultipartsInfo - represnets bucket resources for incomplete multipart uploads.
 type ListMultipartsInfo struct {
-	KeyMarker          string
+	// Together with upload-id-marker, this parameter specifies the multipart upload
-	UploadIDMarker     string
+	// after which listing should begin.
-	NextKeyMarker      string
+	KeyMarker string
+
+	// Together with key-marker, specifies the multipart upload after which listing
+	// should begin. If key-marker is not specified, the upload-id-marker parameter
+	// is ignored.
+	UploadIDMarker string
+
+	// When a list is truncated, this element specifies the value that should be
+	// used for the key-marker request parameter in a subsequent request.
+	NextKeyMarker string
+
+	// When a list is truncated, this element specifies the value that should be
+	// used for the upload-id-marker request parameter in a subsequent request.
 	NextUploadIDMarker string
-	EncodingType       string
+
-	MaxUploads         int
+	// Maximum number of multipart uploads that could have been included in the
-	IsTruncated        bool
+	// response.
-	Uploads            []uploadMetadata
+	MaxUploads int
-	Prefix             string
+
-	Delimiter          string
+	// Indicates whether the returned list of multipart uploads is truncated. A
-	CommonPrefixes     []string
+	// value of true indicates that the list was truncated. The list can be truncated
+	// if the number of multipart uploads exceeds the limit allowed or specified
+	// by max uploads.
+	IsTruncated bool
+
+	// List of all pending uploads.
+	Uploads []uploadMetadata
+
+	// When a prefix is provided in the request, The result contains only keys
+	// starting with the specified prefix.
+	Prefix string
+
+	// A character used to truncate the object prefixes.
+	// NOTE: only supported delimiter is '/'.
+	Delimiter string
+
+	// CommonPrefixes contains all (if there are any) keys between Prefix and the
+	// next occurrence of the string specified by delimiter.
+	CommonPrefixes []string
+
+	EncodingType string // Not supported yet.
 }
 
 // ListObjectsInfo - container for list objects.
 type ListObjectsInfo struct {
+	// Indicates whether the returned list objects response is truncated. A
+	// value of true indicates that the list was truncated. The list can be truncated
+	// if the number of objects exceeds the limit allowed or specified
+	// by max keys.
 	IsTruncated bool
-	NextMarker  string
+
-	Objects     []ObjectInfo
+	// When response is truncated (the IsTruncated element value in the response
-	Prefixes    []string
+	// is true), you can use the key name in this field as marker in the subsequent
+	// request to get next set of objects.
+	//
+	// NOTE: This element is returned only if you have delimiter request parameter
+	// specified.
+	NextMarker string
+
+	// List of objects info for this request.
+	Objects []ObjectInfo
+
+	// List of prefixes for this request.
+	Prefixes []string
 }
 
-// partInfo - various types of individual part resources.
+// partInfo - represents individual part metadata.
 type partInfo struct {
-	PartNumber   int
+	// Part number that identifies the part. This is a positive integer between
+	// 1 and 10,000.
+	PartNumber int
+
+	// Date and time at which the part was uploaded.
 	LastModified time.Time
-	ETag         string
+
-	Size         int64
+	// Entity tag returned when the part was initially uploaded.
+	ETag string
+
+	// Size in bytes of the part.
+	Size int64
 }
 
-// uploadMetadata container capturing metadata on in progress multipart upload in a given bucket
+// uploadMetadata - represents metadata in progress multipart upload.
 type uploadMetadata struct {
-	Object       string
+	// Object name for which the multipart upload was initiated.
-	UploadID     string
+	Object string
-	StorageClass string
+
-	Initiated    time.Time
+	// Unique identifier for this multipart upload.
+	UploadID string
+
+	// Date and time at which the multipart upload was initiated.
+	Initiated time.Time
+
+	StorageClass string // Not supported yet.
 }
 
 // completePart - completed part container.
 type completePart struct {
+	// Part number identifying the part. This is a positive integer between 1 and
+	// 10,000
 	PartNumber int
-	ETag       string
+
+	// Entity tag returned when the part was uploaded.
+	ETag string
 }
 
-// completedParts is a sortable interface for Part slice
+// completedParts - is a collection satisfying sort.Interface.
 type completedParts []completePart
 
 func (a completedParts) Len() int           { return len(a) }
 func (a completedParts) Swap(i, j int)      { a[i], a[j] = a[j], a[i] }
 func (a completedParts) Less(i, j int) bool { return a[i].PartNumber < a[j].PartNumber }
 
-// completeMultipartUpload container for completing multipart upload
+// completeMultipartUpload - represents input fields for completing multipart upload.
 type completeMultipartUpload struct {
 	Parts []completePart `xml:"Part"`
 }

rpc-server-datatypes.go

@@ -16,54 +16,83 @@
 
 package main
 
-// GenericReply generic rpc reply.
+// GenericReply represents any generic RPC reply.
 type GenericReply struct{}
 
-// GenericArgs generic rpc args.
+// GenericArgs represents any generic RPC arguments.
 type GenericArgs struct{}
 
-// ListVolsReply list vols rpc reply.
+// ListVolsReply represents list of vols RPC reply.
 type ListVolsReply struct {
+	// List of volumes stat information.
 	Vols []VolInfo
 }
 
-// ReadFileArgs contains read file arguments.
+// ReadFileArgs represents read file RPC arguments.
 type ReadFileArgs struct {
-	Vol    string
+	// Name of the volume.
-	Path   string
+	Vol string
+
+	// Name of the path.
+	Path string
+
+	// Starting offset to start reading into Buffer.
 	Offset int64
+
+	// Data buffer read from the path at offset.
 	Buffer []byte
 }
 
-// AppendFileArgs contains append file arguments.
+// AppendFileArgs represents append file RPC arguments.
 type AppendFileArgs struct {
-	Vol    string
+	// Name of the volume.
-	Path   string
+	Vol string
+
+	// Name of the path.
+	Path string
+
+	// Data buffer to be saved at path.
 	Buffer []byte
 }
 
-// StatFileArgs contains stat file arguments.
+// StatFileArgs represents stat file RPC arguments.
 type StatFileArgs struct {
-	Vol  string
+	// Name of the volume.
+	Vol string
+
+	// Name of the path.
 	Path string
 }
 
-// DeleteFileArgs contains delete file arguments.
+// DeleteFileArgs represents delete file RPC arguments.
 type DeleteFileArgs struct {
-	Vol  string
+	// Name of the volume.
+	Vol string
+
+	// Name of the path.
 	Path string
 }
 
-// ListDirArgs contains list dir arguments.
+// ListDirArgs represents list contents RPC arguments.
 type ListDirArgs struct {
-	Vol  string
+	// Name of the volume.
+	Vol string
+
+	// Name of the path.
 	Path string
 }
 
-// RenameFileArgs contains rename file arguments.
+// RenameFileArgs represents rename file RPC arguments.
 type RenameFileArgs struct {
-	SrcVol  string
+	// Name of source volume.
+	SrcVol string
+
+	// Source path to be renamed.
 	SrcPath string
-	DstVol  string
+
+	// Name of destination volume.
+	DstVol string
+
+	// Destination path of renamed file.
 	DstPath string
 }

storage-datatypes.go

@@ -21,18 +21,32 @@ import (
 	"time"
 )
 
-// VolInfo - volume info
+// VolInfo - represents volume stat information.
 type VolInfo struct {
-	Name    string
+	// Name of the volume.
+	Name string
+
+	// Date and time when the volume was created.
 	Created time.Time
 }
 
-// FileInfo - file stat information.
+// FileInfo - represents file stat information.
 type FileInfo struct {
-	Volume  string
+	// Name of the volume.
-	Name    string
+	Volume string
-	MD5Sum  string
+
+	// Name of the file.
+	Name string
+
+	// Date and time when the file was last modified.
 	ModTime time.Time
-	Size    int64
+
-	Mode    os.FileMode
+	// Total file size.
+	Size int64
+
+	// File mode bits.
+	Mode os.FileMode
+
+	// Hex encoded md5 checksum of the file.
+	MD5Sum string
 }