From df0064c55f1cd46b7117339acbd2cfa04908a79a Mon Sep 17 00:00:00 2001
From: Antonio Navarro Perez <antnavper@gmail.com>
Date: Fri, 5 Mar 2021 14:03:48 +0100
Subject: [PATCH] Add godoc.

Signed-off-by: Antonio Navarro Perez <antnavper@gmail.com>
---
 etcd/leasedkv.go      | 18 ++++++++++++++----
 etcd/leasedkv_test.go | 14 ++++++++++++++
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/etcd/leasedkv.go b/etcd/leasedkv.go
index 77df1c73c..ad1a46514 100644
--- a/etcd/leasedkv.go
+++ b/etcd/leasedkv.go
@@ -26,15 +26,19 @@ import (
 	"go.etcd.io/etcd/clientv3/clientv3util"
 )
 
+// leasedKV is an etcd key and value attached to a lease. It can be used to detect if a node went down.
+// It will try to renew the lease at any cost after losing it.
+// It will recreate the previous existing value for the key again.
 type leasedKV struct {
 	cli    *clientv3.Client
 	cancel context.CancelFunc
 
-	mu sync.Mutex
-
-	key, value string
-	stopped    bool
+	key        string
 	ttlSeconds int64
+
+	mu      sync.Mutex
+	value   string // protected by mu
+	stopped bool   // protected by mu
 }
 
 func newLeasedKV(cli *clientv3.Client, key string, ttlSeconds int64) *leasedKV {
@@ -45,6 +49,8 @@ func newLeasedKV(cli *clientv3.Client, key string, ttlSeconds int64) *leasedKV {
 	}
 }
 
+// Start creates the key and attaches it to a lease.
+// If the lease cannot be renewed in time, it will try to renew it ad finitum.
 func (l *leasedKV) Start(initValue string) error {
 	l.mu.Lock()
 	defer l.mu.Unlock()
@@ -105,6 +111,8 @@ func (l *leasedKV) consumeLease(ch <-chan *clientv3.LeaseKeepAliveResponse) {
 	}
 }
 
+// Stop will cancel the lease renewal.
+// After calling Stop, this object should be discarded and not used anymore.
 func (l *leasedKV) Stop() {
 	l.mu.Lock()
 	defer l.mu.Unlock()
@@ -116,6 +124,7 @@ func (l *leasedKV) Stop() {
 	l.stopped = true
 }
 
+// Set will change the specific value for this key.
 func (l *leasedKV) Set(ctx context.Context, value string) error {
 	l.mu.Lock()
 	defer l.mu.Unlock()
@@ -131,6 +140,7 @@ func (l *leasedKV) Set(ctx context.Context, value string) error {
 	return nil
 }
 
+// Get will obtain the actual value for the key.
 func (l *leasedKV) Get(ctx context.Context) (string, error) {
 	l.mu.Lock()
 	defer l.mu.Unlock()
diff --git a/etcd/leasedkv_test.go b/etcd/leasedkv_test.go
index 288a02052..bcd1f06de 100644
--- a/etcd/leasedkv_test.go
+++ b/etcd/leasedkv_test.go
@@ -1,3 +1,17 @@
+// Copyright 2017 Pilosa Corp.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package etcd
 
 import (