From 126da483f2e1b19799e8e28d803fdcc99b4e0594 Mon Sep 17 00:00:00 2001
From: Kevin Gillette <extemporalgenome@gmail.com>
Date: Tue, 28 Nov 2023 02:14:34 -0700
Subject: [PATCH] shorter doc comments for fully-deprecated (ignored)
 fields/methods (#397)

---
 codec/decode.go |  9 ++-------
 codec/encode.go |  7 ++-----
 codec/helper.go | 19 ++-----------------
 3 files changed, 6 insertions(+), 29 deletions(-)

diff --git a/codec/decode.go b/codec/decode.go
index d549188d..c8210599 100644
--- a/codec/decode.go
+++ b/codec/decode.go
@@ -1580,14 +1580,9 @@ func (d *Decoder) MustDecode(v interface{}) {
 	d.calls--
 }
 
-// Release releases shared (pooled) resources.
+// Release is a no-op.
 //
-// It is important to call Release() when done with a Decoder, so those resources
-// are released instantly for use by subsequently created Decoders.
-//
-// By default, Release() is automatically called unless the option ExplicitRelease is set.
-//
-// Deprecated: Release is a no-op as pooled resources are not used with an Decoder.
+// Deprecated: Pooled resources are not used with a Decoder.
 // This method is kept for compatibility reasons only.
 func (d *Decoder) Release() {
 }
diff --git a/codec/encode.go b/codec/encode.go
index 70361b5c..411dafee 100644
--- a/codec/encode.go
+++ b/codec/encode.go
@@ -1150,12 +1150,9 @@ func (e *Encoder) MustEncode(v interface{}) {
 	}
 }
 
-// Release releases shared (pooled) resources.
+// Release is a no-op.
 //
-// It is important to call Release() when done with an Encoder, so those resources
-// are released instantly for use by subsequently created Encoders.
-//
-// Deprecated: Release is a no-op as pooled resources are not used with an Encoder.
+// Deprecated: Pooled resources are not used with an Encoder.
 // This method is kept for compatibility reasons only.
 func (e *Encoder) Release() {
 }
diff --git a/codec/helper.go b/codec/helper.go
index 19df27b6..2698d8fc 100644
--- a/codec/helper.go
+++ b/codec/helper.go
@@ -857,26 +857,11 @@ type BasicHandle struct {
 	// Once a Handle has been initialized (used), do not modify this option. It will be ignored.
 	TimeNotBuiltin bool
 
-	// ExplicitRelease configures whether Release() is implicitly called after an encode or
-	// decode call.
-	//
-	// If you will hold onto an Encoder or Decoder for re-use, by calling Reset(...)
-	// on it or calling (Must)Encode repeatedly into a given []byte or io.Writer,
-	// then you do not want it to be implicitly closed after each Encode/Decode call.
-	// Doing so will unnecessarily return resources to the shared pool, only for you to
-	// grab them right after again to do another Encode/Decode call.
-	//
-	// Instead, you configure ExplicitRelease=true, and you explicitly call Release() when
-	// you are truly done.
-	//
-	// As an alternative, you can explicitly set a finalizer - so its resources
-	// are returned to the shared pool before it is garbage-collected. Do it as below:
-	//    runtime.SetFinalizer(e, (*Encoder).Release)
-	//    runtime.SetFinalizer(d, (*Decoder).Release)
+	// ExplicitRelease is ignored and has no effect.
 	//
 	// Deprecated: This is not longer used as pools are only used for long-lived objects
 	// which are shared across goroutines.
-	// Setting this value has no effect. It is maintained for backward compatibility.
+	// It is maintained for backward compatibility.
 	ExplicitRelease bool
 
 	// ---- cache line