From 85ccad7862a35cbebc935776ac057f6bb6cfc75f Mon Sep 17 00:00:00 2001
From: Stanislav Chzhen <s.chzhen@adguard.com>
Date: Fri, 28 Jun 2024 18:05:37 +0300
Subject: [PATCH] all: imp docs

---
 internal/client/persistent.go | 10 +++++-----
 internal/client/storage.go    | 12 ++++++++++++
 internal/home/clients.go      |  2 +-
 3 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/internal/client/persistent.go b/internal/client/persistent.go
index f254e293..ce68986f 100644
--- a/internal/client/persistent.go
+++ b/internal/client/persistent.go
@@ -82,21 +82,21 @@ type Persistent struct {
 	Upstreams []string
 
 	// IPs is a list of IP addresses that identify the client.  The client must
-	// have at least one ID [Persistent.IDsLen].
+	// have at least one ID (IP, subnet, MAC, or ClientID).
 	IPs []netip.Addr
 
 	// Subnets identifying the client.  The client must have at least one ID
-	// [Persistent.IDsLen].
+	// (IP, subnet, MAC, or ClientID).
 	//
 	// TODO(s.chzhen):  Use netutil.Prefix.
 	Subnets []netip.Prefix
 
-	// MACs identifying the client.  The client must have at least one ID
-	// [Persistent.IDsLen].
+	// MACs identifying the client.  The client must have at least one ID (IP,
+	// subnet, MAC, or ClientID).
 	MACs []net.HardwareAddr
 
 	// ClientIDs identifying the client.  The client must have at least one ID
-	// [Persistent.IDsLen].
+	// (IP, subnet, MAC, or ClientID).
 	ClientIDs []string
 
 	// UID is the unique identifier of the persistent client.
diff --git a/internal/client/storage.go b/internal/client/storage.go
index 2caedefc..2053bdf9 100644
--- a/internal/client/storage.go
+++ b/internal/client/storage.go
@@ -227,6 +227,8 @@ func (s *Storage) CloseUpstreams() (err error) {
 
 // ClientRuntime returns a copy of the saved runtime client by ip.  If no such
 // client exists, returns nil.
+//
+// TODO(s.chzhen):  Use it.
 func (s *Storage) ClientRuntime(ip netip.Addr) (rc *Runtime) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -236,6 +238,8 @@ func (s *Storage) ClientRuntime(ip netip.Addr) (rc *Runtime) {
 
 // AddRuntime saves the runtime client information in the storage.  IP address
 // of a client must be unique.  rc must not be nil.
+//
+// TODO(s.chzhen):  Use it.
 func (s *Storage) AddRuntime(rc *Runtime) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -244,6 +248,8 @@ func (s *Storage) AddRuntime(rc *Runtime) {
 }
 
 // SizeRuntime returns the number of the runtime clients.
+//
+// TODO(s.chzhen):  Use it.
 func (s *Storage) SizeRuntime() (n int) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -252,6 +258,8 @@ func (s *Storage) SizeRuntime() (n int) {
 }
 
 // RangeRuntime calls f for each runtime client in an undefined order.
+//
+// TODO(s.chzhen):  Use it.
 func (s *Storage) RangeRuntime(f func(rc *Runtime) (cont bool)) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -260,6 +268,8 @@ func (s *Storage) RangeRuntime(f func(rc *Runtime) (cont bool)) {
 }
 
 // DeleteRuntime removes the runtime client by ip.
+//
+// TODO(s.chzhen):  Use it.
 func (s *Storage) DeleteRuntime(ip netip.Addr) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -269,6 +279,8 @@ func (s *Storage) DeleteRuntime(ip netip.Addr) {
 
 // DeleteBySource removes all runtime clients that have information only from
 // the specified source and returns the number of removed clients.
+//
+// TODO(s.chzhen):  Use it.
 func (s *Storage) DeleteBySource(src Source) (n int) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
diff --git a/internal/home/clients.go b/internal/home/clients.go
index 7b1e9824..aee32f92 100644
--- a/internal/home/clients.go
+++ b/internal/home/clients.go
@@ -348,7 +348,7 @@ func (clients *clientsContainer) periodicUpdate() {
 
 // clientSource checks if client with this IP address already exists and returns
 // the source which updated it last.  It returns [client.SourceNone] if the
-// client doesn't exist.
+// client doesn't exist.  Note that it is only used in tests.
 func (clients *clientsContainer) clientSource(ip netip.Addr) (src client.Source) {
 	clients.lock.Lock()
 	defer clients.lock.Unlock()