Commit a7840b87ed for perl

commit a7840b87edec8cd988552bab5ec3344a701e5594
Author: Richard Leach <rich+perl@hyphen-dash-hyphen.info>
Date:   Wed Sep 30 22:21:00 2026 +0000

    SvPV_free: flesh out why it is precarious in apidoc

diff --git a/sv.h b/sv.h
index 5d841d557f..e49657ae3c 100644
--- a/sv.h
+++ b/sv.h
@@ -1726,7 +1726,13 @@ L</C<SV_CHECK_THINKFIRST_COW_DROP>> before calling this.
 =for apidoc Am|void|SvPV_free|SV * sv

 Frees the PV buffer in C<sv>, leaving things in a precarious state, so should
-only be used as part of a larger operation
+only be used as part of a larger operation.
+
+A C<SvTHINKFIRST> check of some kind must have been performed on the sv prior
+to using C<SvPV_free>, as it is not COW aware.
+
+C<SvCUR> and C<SvLEN> are left unchanged. It is the caller's responsibility
+to set them to values appropriate to the task in hand.

 =cut
 */