From 4de510778b6e55a2238374834d00b03726da76d4 Mon Sep 17 00:00:00 2001
From: Laria Carolin Chabowski <laria@laria.me>
Date: Tue, 3 Oct 2017 14:59:45 +0200
Subject: Documentation

---
 objects/object_file.go | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

(limited to 'objects/object_file.go')

diff --git a/objects/object_file.go b/objects/object_file.go
index 7551193..6143ec2 100644
--- a/objects/object_file.go
+++ b/objects/object_file.go
@@ -7,16 +7,20 @@ import (
 	"strconv"
 )
 
+// FileFragment describes a fragment of a file. It consists of the ID of a blob and the size of the blob.
+// The size is not necessary for reconstruction (the blob object already has a size)
+// but it can speed up random access to the whole file by skipping previous fragments.
+// It is serialized as `Properties` (see there) with the keys `blob` (ID of blob object) and `size` (decimal size of the blob)
 type FileFragment struct {
 	Blob ObjectId
 	Size uint64
 }
 
-func (ff FileFragment) toProperties() properties {
-	return properties{"blob": ff.Blob.String(), "size": strconv.FormatUint(ff.Size, 10)}
+func (ff FileFragment) toProperties() Properties {
+	return Properties{"blob": ff.Blob.String(), "size": strconv.FormatUint(ff.Size, 10)}
 }
 
-func (ff *FileFragment) fromProperties(p properties) error {
+func (ff *FileFragment) fromProperties(p Properties) error {
 	blob, ok := p["blob"]
 	if !ok {
 		return errors.New("Field `blob` is missing")
@@ -41,6 +45,19 @@ func (a FileFragment) Equals(b FileFragment) bool {
 	return a.Blob.Equals(b.Blob) && a.Size == b.Size
 }
 
+// File describes a file object which ties together multiple Blob objects to a file.
+// It is an ordered list of `FileFragment`s. The referenced blobs concatencated in the given order are the content of the file.
+//
+// Example:
+//
+//     blob=sha3-256:1111111111111111111111111111111111111111111111111111111111111111&size=123
+//     blob=sha3-256:1111111111111111111111111111111111111111111111111111111111111111&size=123
+//     blob=sha3-256:2222222222222222222222222222222222222222222222222222222222222222&size=10
+//
+// The file described by this object is 123+123+10 = 256 bytes long and consists of the blobs 111... (two times) and 222...
+//
+// Since the blob IDs and sizes don't change unless the file itself changes and the format will always serialize the same,
+// serializing the same file twice results in exactly the same object with exactly the same ID. It will therefor only be stored once.
 type File []FileFragment
 
 func (f File) Type() ObjectType {
@@ -72,7 +89,7 @@ func (f *File) FromPayload(payload []byte) error {
 			continue
 		}
 
-		props := make(properties)
+		props := make(Properties)
 		if err := props.UnmarshalText(line); err != nil {
 			return nil
 		}
-- 
cgit v1.2.3-54-g00ecf