repo: more documentation

Michael Muré created 7 years ago

Change summary

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

Detailed changes

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)
 }

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
 }
 

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,

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)