From c06ec45f09734ddc31340989b9c75ae8bae859a9 Mon Sep 17 00:00:00 2001
From: Josh Bleecher Snyder <josh@tailscale.com>
Date: Fri, 21 May 2021 11:10:05 -0700
Subject: [PATCH] internal/deephash: document MapIter shims

These exist so we can use the optimized MapIter APIs
while still working with released versions of Go.
They're pretty simple, but some docs won't hurt.

Signed-off-by: Josh Bleecher Snyder <josh@tailscale.com>
---
 internal/deephash/mapiter.go        | 12 ++++++++++--
 internal/deephash/mapiter_future.go |  8 ++++++++
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/internal/deephash/mapiter.go b/internal/deephash/mapiter.go
index a45275dc0..a47eb76b4 100644
--- a/internal/deephash/mapiter.go
+++ b/internal/deephash/mapiter.go
@@ -8,10 +8,18 @@
 
 import "reflect"
 
-func iterKey(iter *reflect.MapIter, scratch reflect.Value) reflect.Value {
+// iterKey returns the current iter key.
+// scratch is a re-usable reflect.Value.
+// iterKey may store the iter key in scratch and return scratch,
+// or it may allocate and return a new reflect.Value.
+func iterKey(iter *reflect.MapIter, _ reflect.Value) reflect.Value {
 	return iter.Key()
 }
 
-func iterVal(iter *reflect.MapIter, scratch reflect.Value) reflect.Value {
+// iterVal returns the current iter val.
+// scratch is a re-usable reflect.Value.
+// iterVal may store the iter val in scratch and return scratch,
+// or it may allocate and return a new reflect.Value.
+func iterVal(iter *reflect.MapIter, _ reflect.Value) reflect.Value {
 	return iter.Value()
 }
diff --git a/internal/deephash/mapiter_future.go b/internal/deephash/mapiter_future.go
index 6e18dbd6a..a92fbc75f 100644
--- a/internal/deephash/mapiter_future.go
+++ b/internal/deephash/mapiter_future.go
@@ -8,11 +8,19 @@
 
 import "reflect"
 
+// iterKey returns the current iter key.
+// scratch is a re-usable reflect.Value.
+// iterKey may store the iter key in scratch and return scratch,
+// or it may allocate and return a new reflect.Value.
 func iterKey(iter *reflect.MapIter, scratch reflect.Value) reflect.Value {
 	iter.SetKey(scratch)
 	return scratch
 }
 
+// iterVal returns the current iter val.
+// scratch is a re-usable reflect.Value.
+// iterVal may store the iter val in scratch and return scratch,
+// or it may allocate and return a new reflect.Value.
 func iterVal(iter *reflect.MapIter, scratch reflect.Value) reflect.Value {
 	iter.SetValue(scratch)
 	return scratch