shorter doc comments for fully-deprecated (ignored) fields/methods (#397

)

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

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

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