document save_gp() and the GVf_INTRO flag

3 files changed, 18 insertions, 1 deletions

diff --git a/embed.fnc b/embed.fnc
index f29c810952..877438a70e 100644
--- a/embed.fnc
+++ b/embed.fnc
@@ -1279,7 +1279,7 @@ Apmb	|void	|save_freepv	|NULLOK char* pv
 Ap	|void	|save_generic_svref|NN SV** sptr
 Ap	|void	|save_generic_pvref|NN char** str
 Ap	|void	|save_shared_pvref|NN char** str
-Ap	|void	|save_gp	|NN GV* gv|I32 empty
+Adp	|void	|save_gp	|NN GV* gv|I32 empty
 Ap	|HV*	|save_hash	|NN GV* gv
 Ap	|void	|save_hints
 Amp	|void	|save_helem	|NN HV *hv|NN SV *key|NN SV **sptr
diff --git a/gv.h b/gv.h
index a6b695ed3d..e3357bc4de 100644
--- a/gv.h
+++ b/gv.h
@@ -151,6 +151,10 @@ Return the CV from the GV.
 #define GvENAME_HEK(gv) GvNAME_HEK(GvEGV(gv) ? GvEGV(gv) : gv)
 #define GvESTASH(gv)	GvSTASH(GvEGV(gv) ? GvEGV(gv) : gv)
 
+/* GVf_INTRO is one-shot flag which indicates that the next assignment
+   of a reference to the glob is to be localised; it distinguishes
+   'local *g = $ref' from '*g = $ref'.
+*/
 #define GVf_INTRO	0x01
 #define GVf_MULTI	0x02
 #define GVf_ASSUMECV	0x04
diff --git a/scope.c b/scope.c
index e5687f4ac2..c08eda06c8 100644
--- a/scope.c
+++ b/scope.c
@@ -298,6 +298,19 @@ Perl_save_set_svflags(pTHX_ SV* sv, U32 mask, U32 val)
     SS_ADD_END(4);
 }
 
+/*
+=for apidoc save_gp
+
+Saves the current GP of gv on the save stack to be restored on scope exit.
+
+If empty is true, replace the GP with a new GP.
+
+If empty is false, mark gv with GVf_INTRO so the next reference
+assigned is localized, which is how C< local *foo = $someref; > works.
+
+=cut
+*/
+
 void
 Perl_save_gp(pTHX_ GV *gv, I32 empty)
 {