From c3a5213f829444452e1971822529a57da613831d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20Mur=C3=A9?= <batolettre@gmail.com>
Date: Mon, 24 Sep 2018 12:46:39 +0200
Subject: [PATCH] repo: more documentation

---
 repository/git.go                 | 8 ++++++++
 repository/repo.go                | 8 ++++++++
 util/lamport/lamport.go           | 3 +++
 util/lamport/persisted_lamport.go | 5 +++++
 4 files changed, 24 insertions(+)

diff --git a/repository/git.go b/repository/git.go
index d01a8e68..db411792 100644
--- a/repository/git.go
+++ b/repository/git.go
@@ -366,6 +366,7 @@ func (repo *GitRepo) createClocks() error {
 	return nil
 }
 
+// LoadClocks read the clocks values from the on-disk repo
 func (repo *GitRepo) LoadClocks() error {
 	createClock, err := lamport.LoadPersisted(repo.GetPath() + createClockFile)
 	if err != nil {
@@ -382,6 +383,7 @@ func (repo *GitRepo) LoadClocks() error {
 	return nil
 }
 
+// WriteClocks write the clocks values into the repo
 func (repo *GitRepo) WriteClocks() error {
 	err := repo.createClock.Write()
 	if err != nil {
@@ -396,18 +398,24 @@ func (repo *GitRepo) WriteClocks() error {
 	return nil
 }
 
+// CreateTimeIncrement increment the creation clock and return the new value.
 func (repo *GitRepo) CreateTimeIncrement() (lamport.Time, error) {
 	return repo.createClock.Increment()
 }
 
+// EditTimeIncrement increment the edit clock and return the new value.
 func (repo *GitRepo) EditTimeIncrement() (lamport.Time, error) {
 	return repo.editClock.Increment()
 }
 
+// CreateWitness witness another create time and increment the corresponding clock
+// if needed.
 func (repo *GitRepo) CreateWitness(time lamport.Time) error {
 	return repo.createClock.Witness(time)
 }
 
+// EditWitness witness another edition time and increment the corresponding clock
+// if needed.
 func (repo *GitRepo) EditWitness(time lamport.Time) error {
 	return repo.editClock.Witness(time)
 }
diff --git a/repository/repo.go b/repository/repo.go
index 053837db..0cddf38a 100644
--- a/repository/repo.go
+++ b/repository/repo.go
@@ -76,16 +76,24 @@ type Repo interface {
 type ClockedRepo interface {
 	Repo
 
+	// LoadClocks read the clocks values from the on-disk repo
 	LoadClocks() error
 
+	// WriteClocks write the clocks values into the repo
 	WriteClocks() error
 
+	// CreateTimeIncrement increment the creation clock and return the new value.
 	CreateTimeIncrement() (lamport.Time, error)
 
+	// EditTimeIncrement increment the edit clock and return the new value.
 	EditTimeIncrement() (lamport.Time, error)
 
+	// CreateWitness witness another create time and increment the corresponding
+	// clock if needed.
 	CreateWitness(time lamport.Time) error
 
+	// EditWitness witness another edition time and increment the corresponding
+	// clock if needed.
 	EditWitness(time lamport.Time) error
 }
 
diff --git a/util/lamport/lamport.go b/util/lamport/lamport.go
index 640c58bc..0372bb6f 100644
--- a/util/lamport/lamport.go
+++ b/util/lamport/lamport.go
@@ -41,12 +41,15 @@ type Clock struct {
 // Time is the value of a Clock.
 type Time uint64
 
+// NewClock create a new clock with the value 1.
+// Value 0 is considered as invalid.
 func NewClock() Clock {
 	return Clock{
 		counter: 1,
 	}
 }
 
+// NewClockWithTime create a new clock with a value.
 func NewClockWithTime(time uint64) Clock {
 	return Clock{
 		counter: time,
diff --git a/util/lamport/persisted_lamport.go b/util/lamport/persisted_lamport.go
index 22b23dcb..ab4b93b1 100644
--- a/util/lamport/persisted_lamport.go
+++ b/util/lamport/persisted_lamport.go
@@ -12,6 +12,7 @@ type Persisted struct {
 	filePath string
 }
 
+// NewPersisted create a new persisted Lamport clock
 func NewPersisted(filePath string) (*Persisted, error) {
 	clock := &Persisted{
 		Clock:    NewClock(),
@@ -27,6 +28,7 @@ func NewPersisted(filePath string) (*Persisted, error) {
 	return clock, nil
 }
 
+// LoadPersisted load a persisted Lamport clock from a file
 func LoadPersisted(filePath string) (*Persisted, error) {
 	clock := &Persisted{
 		filePath: filePath,
@@ -40,11 +42,14 @@ func LoadPersisted(filePath string) (*Persisted, error) {
 	return clock, nil
 }
 
+// Increment is used to return the value of the lamport clock and increment it afterwards
 func (c *Persisted) Increment() (Time, error) {
 	time := c.Clock.Increment()
 	return time, c.Write()
 }
 
+// Witness is called to update our local clock if necessary after
+// witnessing a clock value received from another process
 func (c *Persisted) Witness(time Time) error {
 	// TODO: rework so that we write only when the clock was actually updated
 	c.Clock.Witness(time)