This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
document several optree construction functions
authorZefram <zefram@fysh.org>
Sun, 22 Aug 2010 20:55:36 +0000 (21:55 +0100)
committerFlorian Ragwitz <rafl@debian.org>
Mon, 23 Aug 2010 10:06:38 +0000 (12:06 +0200)
embed.fnc
op.c

index ac0c892..7c129b5 100644 (file)
--- a/embed.fnc
+++ b/embed.fnc
@@ -768,26 +768,26 @@ p |void   |my_unexec
 Apa    |OP*    |newANONLIST    |NULLOK OP* o
 Apa    |OP*    |newANONHASH    |NULLOK OP* o
 Ap     |OP*    |newANONSUB     |I32 floor|NULLOK OP* proto|NULLOK OP* block
-Ap   |OP*    |newASSIGNOP    |I32 flags|NULLOK OP* left|I32 optype|NULLOK OP* right
-Ap   |OP*    |newCONDOP      |I32 flags|NN OP* first|NULLOK OP* trueop|NULLOK OP* falseop
+Apda   |OP*    |newASSIGNOP    |I32 flags|NULLOK OP* left|I32 optype|NULLOK OP* right
+Apda   |OP*    |newCONDOP      |I32 flags|NN OP* first|NULLOK OP* trueop|NULLOK OP* falseop
 Apd    |CV*    |newCONSTSUB    |NULLOK HV* stash|NULLOK const char* name|NULLOK SV* sv
 #ifdef PERL_MAD
 Ap     |OP*    |newFORM        |I32 floor|NULLOK OP* o|NULLOK OP* block
 #else
 Ap     |void   |newFORM        |I32 floor|NULLOK OP* o|NULLOK OP* block
 #endif
-Ap   |OP*    |newFOROP       |I32 flags|NULLOK char* label|line_t forline \
+Apda   |OP*    |newFOROP       |I32 flags|NULLOK char* label|line_t forline \
                                |NULLOK OP* sv|NN OP* expr|NULLOK OP* block|NULLOK OP* cont
-Ap   |OP*    |newGIVENOP     |NN OP* cond|NN OP* block|PADOFFSET defsv_off
-Ap   |OP*    |newLOGOP       |I32 optype|I32 flags|NN OP *first|NN OP *other
-Ap   |OP*    |newLOOPEX      |I32 type|NN OP* label
-Ap   |OP*    |newLOOPOP      |I32 flags|I32 debuggable|NULLOK OP* expr|NULLOK OP* block
-Ap   |OP*    |newNULLLIST
-Ap   |OP*    |newOP          |I32 optype|I32 flags
+Apda   |OP*    |newGIVENOP     |NN OP* cond|NN OP* block|PADOFFSET defsv_off
+Apda   |OP*    |newLOGOP       |I32 optype|I32 flags|NN OP *first|NN OP *other
+Apda   |OP*    |newLOOPEX      |I32 type|NN OP* label
+Apda   |OP*    |newLOOPOP      |I32 flags|I32 debuggable|NULLOK OP* expr|NULLOK OP* block
+Apda   |OP*    |newNULLLIST
+Apda   |OP*    |newOP          |I32 optype|I32 flags
 Ap     |void   |newPROG        |NN OP* o
-Ap   |OP*    |newRANGE       |I32 flags|NN OP* left|NN OP* right
-Ap   |OP*    |newSLICEOP     |I32 flags|NULLOK OP* subscript|NULLOK OP* listop
-Ap   |OP*    |newSTATEOP     |I32 flags|NULLOK char* label|NULLOK OP* o
+Apda   |OP*    |newRANGE       |I32 flags|NN OP* left|NN OP* right
+Apda   |OP*    |newSLICEOP     |I32 flags|NULLOK OP* subscript|NULLOK OP* listop
+Apda   |OP*    |newSTATEOP     |I32 flags|NULLOK char* label|NULLOK OP* o
 Ap     |CV*    |newSUB         |I32 floor|NULLOK OP* o|NULLOK OP* proto|NULLOK OP* block
 ApM    |CV *   |newXS_flags    |NULLOK const char *name|NN XSUBADDR_t subaddr\
                                |NN const char *const filename \
@@ -796,26 +796,26 @@ Apd       |CV*    |newXS          |NULLOK const char *name|NN XSUBADDR_t subaddr\
                                |NN const char *filename
 AmdbR  |AV*    |newAV
 Apa    |OP*    |newAVREF       |NN OP* o
-Ap   |OP*    |newBINOP       |I32 type|I32 flags|NULLOK OP* first|NULLOK OP* last
+Apda   |OP*    |newBINOP       |I32 type|I32 flags|NULLOK OP* first|NULLOK OP* last
 Apa    |OP*    |newCVREF       |I32 flags|NULLOK OP* o
-Ap   |OP*    |newGVOP        |I32 type|I32 flags|NN GV* gv
+Apda   |OP*    |newGVOP        |I32 type|I32 flags|NN GV* gv
 Apa    |GV*    |newGVgen       |NN const char* pack
 Apa    |OP*    |newGVREF       |I32 type|NULLOK OP* o
 ApaR   |OP*    |newHVREF       |NN OP* o
 AmdbR  |HV*    |newHV
 ApaR   |HV*    |newHVhv        |NULLOK HV *hv
 Apabm  |IO*    |newIO
-Ap   |OP*    |newLISTOP      |I32 type|I32 flags|NULLOK OP* first|NULLOK OP* last
+Apda   |OP*    |newLISTOP      |I32 type|I32 flags|NULLOK OP* first|NULLOK OP* last
 #ifdef USE_ITHREADS
-Ap   |OP*    |newPADOP       |I32 type|I32 flags|NN SV* sv
+Apda   |OP*    |newPADOP       |I32 type|I32 flags|NN SV* sv
 #endif
-Ap   |OP*    |newPMOP        |I32 type|I32 flags
-Ap   |OP*    |newPVOP        |I32 type|I32 flags|NULLOK char* pv
+Apda   |OP*    |newPMOP        |I32 type|I32 flags
+Apda   |OP*    |newPVOP        |I32 type|I32 flags|NULLOK char* pv
 Apa    |SV*    |newRV          |NN SV *const sv
 Apda   |SV*    |newRV_noinc    |NN SV *const sv
 Apda   |SV*    |newSV          |const STRLEN len
 Apa    |OP*    |newSVREF       |NN OP* o
-Ap   |OP*    |newSVOP        |I32 type|I32 flags|NN SV* sv
+Apda   |OP*    |newSVOP        |I32 type|I32 flags|NN SV* sv
 Apda   |SV*    |newSViv        |const IV i
 Apda   |SV*    |newSVuv        |const UV u
 Apda   |SV*    |newSVnv        |const NV n
@@ -829,9 +829,9 @@ Apa |SV*    |vnewSVpvf      |NN const char *const pat|NULLOK va_list *const args
 Apd    |SV*    |newSVrv        |NN SV *const rv|NULLOK const char *const classname
 Apda   |SV*    |newSVsv        |NULLOK SV *const old
 Apda   |SV*    |newSV_type     |const svtype type
-Ap   |OP*    |newUNOP        |I32 type|I32 flags|NULLOK OP* first
-Ap   |OP*    |newWHENOP      |NULLOK OP* cond|NN OP* block
-Ap   |OP*    |newWHILEOP     |I32 flags|I32 debuggable|NULLOK LOOP* loop \
+Apda   |OP*    |newUNOP        |I32 type|I32 flags|NULLOK OP* first
+Apda   |OP*    |newWHENOP      |NULLOK OP* cond|NN OP* block
+Apda   |OP*    |newWHILEOP     |I32 flags|I32 debuggable|NULLOK LOOP* loop \
                                |I32 whileline|NULLOK OP* expr|NULLOK OP* block|NULLOK OP* cont \
                                |I32 has_my
 Apa    |PERL_SI*|new_stackinfo|I32 stitems|I32 cxitems
diff --git a/op.c b/op.c
index 764b329..0979fc1 100644 (file)
--- a/op.c
+++ b/op.c
@@ -3050,6 +3050,17 @@ Perl_mad_free(pTHX_ MADPROP* mp)
 
 #endif
 
+/*
+=head1 Optree construction
+
+=for apidoc Am|OP *|newNULLLIST
+
+Constructs, checks, and returns a new C<stub> op, which represents an
+empty list expression.
+
+=cut
+*/
+
 OP *
 Perl_newNULLLIST(pTHX)
 {
@@ -3065,6 +3076,18 @@ S_force_list(pTHX_ OP *o)
     return o;
 }
 
+/*
+=for apidoc Am|OP *|newLISTOP|I32 type|I32 flags|OP *first|OP *last
+
+Constructs, checks, and returns an op of any list type.  I<type> is
+the opcode.  I<flags> gives the eight bits of C<op_flags>, except that
+C<OPf_KIDS> will be set automatically if required.  I<first> and I<last>
+supply up to two ops to be direct children of the list op; they are
+consumed by this function and become part of the constructed op tree.
+
+=cut
+*/
+
 OP *
 Perl_newLISTOP(pTHX_ I32 type, I32 flags, OP *first, OP *last)
 {
@@ -3101,6 +3124,17 @@ Perl_newLISTOP(pTHX_ I32 type, I32 flags, OP *first, OP *last)
     return CHECKOP(type, listop);
 }
 
+/*
+=for apidoc Am|OP *|newOP|I32 type|I32 flags
+
+Constructs, checks, and returns an op of any base type (any type that
+has no extra fields).  I<type> is the opcode.  I<flags> gives the
+eight bits of C<op_flags>, and, shifted up eight bits, the eight bits
+of C<op_private>.
+
+=cut
+*/
+
 OP *
 Perl_newOP(pTHX_ I32 type, I32 flags)
 {
@@ -3129,6 +3163,20 @@ Perl_newOP(pTHX_ I32 type, I32 flags)
     return CHECKOP(type, o);
 }
 
+/*
+=for apidoc Am|OP *|newUNOP|I32 type|I32 flags|OP *first
+
+Constructs, checks, and returns an op of any unary type.  I<type> is
+the opcode.  I<flags> gives the eight bits of C<op_flags>, except that
+C<OPf_KIDS> will be set automatically if required, and, shifted up eight
+bits, the eight bits of C<op_private>, except that the bit with value 1
+is automatically set.  I<first> supplies an optional op to be the direct
+child of the unary op; it is consumed by this function and become part
+of the constructed op tree.
+
+=cut
+*/
+
 OP *
 Perl_newUNOP(pTHX_ I32 type, I32 flags, OP *first)
 {
@@ -3161,6 +3209,20 @@ Perl_newUNOP(pTHX_ I32 type, I32 flags, OP *first)
     return fold_constants((OP *) unop);
 }
 
+/*
+=for apidoc Am|OP *|newBINOP|I32 type|I32 flags|OP *first|OP *last
+
+Constructs, checks, and returns an op of any binary type.  I<type>
+is the opcode.  I<flags> gives the eight bits of C<op_flags>, except
+that C<OPf_KIDS> will be set automatically, and, shifted up eight bits,
+the eight bits of C<op_private>, except that the bit with value 1 or
+2 is automatically set as required.  I<first> and I<last> supply up to
+two ops to be the direct children of the binary op; they are consumed
+by this function and become part of the constructed op tree.
+
+=cut
+*/
+
 OP *
 Perl_newBINOP(pTHX_ I32 type, I32 flags, OP *first, OP *last)
 {
@@ -3559,6 +3621,16 @@ S_pmtrans(pTHX_ OP *o, OP *expr, OP *repl)
     return o;
 }
 
+/*
+=for apidoc Am|OP *|newPMOP|I32 type|I32 flags
+
+Constructs, checks, and returns an op of any pattern matching type.
+I<type> is the opcode.  I<flags> gives the eight bits of C<op_flags>
+and, shifted up eight bits, the eight bits of C<op_private>.
+
+=cut
+*/
+
 OP *
 Perl_newPMOP(pTHX_ I32 type, I32 flags)
 {
@@ -3803,6 +3875,17 @@ Perl_pmruntime(pTHX_ OP *o, OP *expr, bool isreg)
     return (OP*)pm;
 }
 
+/*
+=for apidoc Am|OP *|newSVOP|I32 type|I32 flags|SV *sv
+
+Constructs, checks, and returns an op of any type that involves an
+embedded SV.  I<type> is the opcode.  I<flags> gives the eight bits
+of C<op_flags>.  I<sv> gives the SV to embed in the op; this function
+takes ownership of one reference to it.
+
+=cut
+*/
+
 OP *
 Perl_newSVOP(pTHX_ I32 type, I32 flags, SV *sv)
 {
@@ -3829,6 +3912,21 @@ Perl_newSVOP(pTHX_ I32 type, I32 flags, SV *sv)
 }
 
 #ifdef USE_ITHREADS
+
+/*
+=for apidoc Am|OP *|newPADOP|I32 type|I32 flags|SV *sv
+
+Constructs, checks, and returns an op of any type that involves a
+reference to a pad element.  I<type> is the opcode.  I<flags> gives the
+eight bits of C<op_flags>.  A pad slot is automatically allocated, and
+is populated with I<sv>; this function takes ownership of one reference
+to it.
+
+This function only exists if Perl has been compiled to use ithreads.
+
+=cut
+*/
+
 OP *
 Perl_newPADOP(pTHX_ I32 type, I32 flags, SV *sv)
 {
@@ -3857,7 +3955,20 @@ Perl_newPADOP(pTHX_ I32 type, I32 flags, SV *sv)
        padop->op_targ = pad_alloc(type, SVs_PADTMP);
     return CHECKOP(type, padop);
 }
-#endif
+
+#endif /* !USE_ITHREADS */
+
+/*
+=for apidoc Am|OP *|newGVOP|I32 type|I32 flags|GV *gv
+
+Constructs, checks, and returns an op of any type that involves an
+embedded reference to a GV.  I<type> is the opcode.  I<flags> gives the
+eight bits of C<op_flags>.  I<gv> identifies the GV that the op should
+reference; calling this function does not transfer ownership of any
+reference to it.
+
+=cut
+*/
 
 OP *
 Perl_newGVOP(pTHX_ I32 type, I32 flags, GV *gv)
@@ -3874,6 +3985,18 @@ Perl_newGVOP(pTHX_ I32 type, I32 flags, GV *gv)
 #endif
 }
 
+/*
+=for apidoc Am|OP *|newPVOP|I32 type|I32 flags|char *pv
+
+Constructs, checks, and returns an op of any type that involves an
+embedded C-level pointer (PV).  I<type> is the opcode.  I<flags> gives
+the eight bits of C<op_flags>.  I<pv> supplies the C-level pointer, which
+must have been allocated using L</PerlMemShared_malloc>; the memory will
+be freed when the op is destroyed.
+
+=cut
+*/
+
 OP *
 Perl_newPVOP(pTHX_ I32 type, I32 flags, char *pv)
 {
@@ -4191,6 +4314,22 @@ Perl_dofile(pTHX_ OP *term, I32 force_builtin)
     return doop;
 }
 
+/*
+=head1 Optree construction
+
+=for apidoc Am|OP *|newSLICEOP|I32 flags|OP *subscript|OP *listval
+
+Constructs, checks, and returns an C<lslice> (list slice) op.  I<flags>
+gives the eight bits of C<op_flags>, except that C<OPf_KIDS> will
+be set automatically, and, shifted up eight bits, the eight bits of
+C<op_private>, except that the bit with value 1 or 2 is automatically
+set as required.  I<listval> and I<subscript> supply the parameters of
+the slice; they are consumed by this function and become part of the
+constructed op tree.
+
+=cut
+*/
+
 OP *
 Perl_newSLICEOP(pTHX_ I32 flags, OP *subscript, OP *listval)
 {
@@ -4243,6 +4382,29 @@ S_is_list_assignment(pTHX_ register const OP *o)
     return FALSE;
 }
 
+/*
+=for apidoc Am|OP *|newASSIGNOP|I32 flags|OP *left|I32 optype|OP *right
+
+Constructs, checks, and returns an assignment op.  I<left> and I<right>
+supply the parameters of the assignment; they are consumed by this
+function and become part of the constructed op tree.
+
+If I<optype> is C<OP_ANDASSIGN>, C<OP_ORASSIGN>, or C<OP_DORASSIGN>, then
+a suitable conditional optree is constructed.  If I<optype> is the opcode
+of a binary operator, such as C<OP_BIT_OR>, then an op is constructed that
+performs the binary operation and assigns the result to the left argument.
+Either way, if I<optype> is non-zero then I<flags> has no effect.
+
+If I<optype> is zero, then a plain scalar or list assignment is
+constructed.  Which type of assignment it is is automatically determined.
+I<flags> gives the eight bits of C<op_flags>, except that C<OPf_KIDS>
+will be set automatically, and, shifted up eight bits, the eight bits
+of C<op_private>, except that the bit with value 1 or 2 is automatically
+set as required.
+
+=cut
+*/
+
 OP *
 Perl_newASSIGNOP(pTHX_ I32 flags, OP *left, I32 optype, OP *right)
 {
@@ -4491,6 +4653,24 @@ Perl_newASSIGNOP(pTHX_ I32 flags, OP *left, I32 optype, OP *right)
     return o;
 }
 
+/*
+=for apidoc Am|OP *|newSTATEOP|I32 flags|char *label|OP *o
+
+Constructs a state op (COP).  The state op is normally a C<nextstate> op,
+but will be a C<dbstate> op if debugging is enabled for currently-compiled
+code.  The state op is populated from L</PL_curcop> (or L</PL_compiling>).
+If I<label> is non-null, it supplies the name of a label to attach to
+the state op; this function takes ownership of the memory pointed at by
+I<label>, and will free it.  I<flags> gives the eight bits of C<op_flags>
+for the state op.
+
+If I<o> is null, the state op is returned.  Otherwise the state op is
+combined with I<o> into a C<lineseq> list op, which is returned.  I<o>
+is consumed by this function and becomes part of the returned op tree.
+
+=cut
+*/
+
 OP *
 Perl_newSTATEOP(pTHX_ I32 flags, char *label, OP *o)
 {
@@ -4568,6 +4748,19 @@ Perl_newSTATEOP(pTHX_ I32 flags, char *label, OP *o)
     return prepend_elem(OP_LINESEQ, (OP*)cop, o);
 }
 
+/*
+=for apidoc Am|OP *|newLOGOP|I32 type|I32 flags|OP *first|OP *other
+
+Constructs, checks, and returns a logical (flow control) op.  I<type>
+is the opcode.  I<flags> gives the eight bits of C<op_flags>, except
+that C<OPf_KIDS> will be set automatically, and, shifted up eight bits,
+the eight bits of C<op_private>, except that the bit with value 1 is
+automatically set.  I<first> supplies the expression controlling the
+flow, and I<other> supplies the side (alternate) chain of ops; they are
+consumed by this function and become part of the constructed op tree.
+
+=cut
+*/
 
 OP *
 Perl_newLOGOP(pTHX_ I32 type, I32 flags, OP *first, OP *other)
@@ -4784,6 +4977,20 @@ S_new_logop(pTHX_ I32 type, I32 flags, OP** firstp, OP** otherp)
     return o;
 }
 
+/*
+=for apidoc Am|OP *|newCONDOP|I32 flags|OP *first|OP *trueop|OP *falseop
+
+Constructs, checks, and returns a conditional-expression (C<cond_expr>)
+op.  I<flags> gives the eight bits of C<op_flags>, except that C<OPf_KIDS>
+will be set automatically, and, shifted up eight bits, the eight bits of
+C<op_private>, except that the bit with value 1 is automatically set.
+I<first> supplies the expression selecting between the two branches,
+and I<trueop> and I<falseop> supply the branches; they are consumed by
+this function and become part of the constructed op tree.
+
+=cut
+*/
+
 OP *
 Perl_newCONDOP(pTHX_ I32 flags, OP *first, OP *trueop, OP *falseop)
 {
@@ -4849,6 +5056,20 @@ Perl_newCONDOP(pTHX_ I32 flags, OP *first, OP *trueop, OP *falseop)
     return o;
 }
 
+/*
+=for apidoc Am|OP *|newRANGE|I32 flags|OP *left|OP *right
+
+Constructs and returns a C<range> op, with subordinate C<flip> and
+C<flop> ops.  I<flags> gives the eight bits of C<op_flags> for the
+C<flip> op and, shifted up eight bits, the eight bits of C<op_private>
+for both the C<flip> and C<range> ops, except that the bit with value
+1 is automatically set.  I<left> and I<right> supply the expressions
+controlling the endpoints of the range; they are consumed by this function
+and become part of the constructed op tree.
+
+=cut
+*/
+
 OP *
 Perl_newRANGE(pTHX_ I32 flags, OP *left, OP *right)
 {
@@ -4898,6 +5119,22 @@ Perl_newRANGE(pTHX_ I32 flags, OP *left, OP *right)
     return o;
 }
 
+/*
+=for apidoc Am|OP *|newLOOPOP|I32 flags|I32 debuggable|OP *expr|OP *block
+
+Constructs, checks, and returns an op tree expressing a loop.  This is
+only a loop in the control flow through the op tree; it does not have
+the heavyweight loop structure that allows exiting the loop by C<last>
+and suchlike.  I<flags> gives the eight bits of C<op_flags> for the
+top-level op, except that some bits will be set automatically as required.
+I<expr> supplies the expression controlling loop iteration, and I<block>
+supplies the body of the loop; they are consumed by this function and
+become part of the constructed op tree.  I<debuggable> is currently
+unused and should always be 1.
+
+=cut
+*/
+
 OP *
 Perl_newLOOPOP(pTHX_ I32 flags, I32 debuggable, OP *expr, OP *block)
 {
@@ -4962,6 +5199,31 @@ Perl_newLOOPOP(pTHX_ I32 flags, I32 debuggable, OP *expr, OP *block)
     return o;
 }
 
+/*
+=for apidoc Am|OP *|newWHILEOP|I32 flags|I32 debuggable|LOOP *loop|I32 whileline|OP *expr|OP *block|OP *cont|I32 has_my
+
+Constructs, checks, and returns an op tree expressing a C<while> loop.
+This is a heavyweight loop, with structure that allows exiting the loop
+by C<last> and suchlike.
+
+I<loop> is an optional preconstructed C<enterloop> op to use in the
+loop; if it is null then a suitable op will be constructed automatically.
+I<expr> supplies the loop's controlling expression.  I<block> supplies the
+main body of the loop, and I<cont> optionally supplies a C<continue> block
+that operates as a second half of the body.  All of these optree inputs
+are consumed by this function and become part of the constructed op tree.
+
+I<flags> gives the eight bits of C<op_flags> for the C<leaveloop>
+op and, shifted up eight bits, the eight bits of C<op_private> for
+the C<leaveloop> op, except that (in both cases) some bits will be set
+automatically.  I<debuggable> is currently unused and should always be 1.
+I<whileline> is the line number that should be attributed to the loop's
+controlling expression.  I<has_my> can be supplied as true to force the
+loop body to be enclosed in its own scope.
+
+=cut
+*/
+
 OP *
 Perl_newWHILEOP(pTHX_ I32 flags, I32 debuggable, LOOP *loop, I32
 whileline, OP *expr, OP *block, OP *cont, I32 has_my)
@@ -5065,6 +5327,33 @@ whileline, OP *expr, OP *block, OP *cont, I32 has_my)
     return o;
 }
 
+/*
+=for apidoc Am|OP *|newFOROP|I32 flags|char *label|line_t forline|OP *sv|OP *expr|OP *block|OP *cont
+
+Constructs, checks, and returns an op tree expressing a C<foreach>
+loop (iteration through a list of values).  This is a heavyweight loop,
+with structure that allows exiting the loop by C<last> and suchlike.
+
+I<sv> optionally supplies the variable that will be aliased to each
+item in turn; if null, it defaults to C<$_> (either lexical or global).
+I<expr> supplies the list of values to iterate over.  I<block> supplies
+the main body of the loop, and I<cont> optionally supplies a C<continue>
+block that operates as a second half of the body.  All of these optree
+inputs are consumed by this function and become part of the constructed
+op tree.
+
+I<flags> gives the eight bits of C<op_flags> for the C<leaveloop>
+op and, shifted up eight bits, the eight bits of C<op_private> for
+the C<leaveloop> op, except that (in both cases) some bits will be set
+automatically.  I<forline> is the line number that should be attributed
+to the loop's list expression.  If I<label> is non-null, it supplies
+the name of a label to attach to the state op at the start of the loop;
+this function takes ownership of the memory pointed at by I<label>,
+and will free it.
+
+=cut
+*/
+
 OP *
 Perl_newFOROP(pTHX_ I32 flags, char *label, line_t forline, OP *sv, OP *expr, OP *block, OP *cont)
 {
@@ -5191,6 +5480,17 @@ Perl_newFOROP(pTHX_ I32 flags, char *label, line_t forline, OP *sv, OP *expr, OP
     return newSTATEOP(0, label, wop);
 }
 
+/*
+=for apidoc Am|OP *|newLOOPEX|I32 type|OP *label
+
+Constructs, checks, and returns a loop-exiting op (such as C<goto>
+or C<last>).  I<type> is the opcode.  I<label> supplies the parameter
+determining the target of the op; it is consumed by this function and
+become part of the constructed op tree.
+
+=cut
+*/
+
 OP*
 Perl_newLOOPEX(pTHX_ I32 type, OP *label)
 {
@@ -5381,6 +5681,19 @@ S_looks_like_bool(pTHX_ const OP *o)
     }
 }
 
+/*
+=for apidoc Am|OP *|newGIVENOP|OP *cond|OP *block|PADOFFSET defsv_off
+
+Constructs, checks, and returns an op tree expressing a C<given> block.
+I<cond> supplies the expression that will be locally assigned to a lexical
+variable, and I<block> supplies the body of the C<given> construct; they
+are consumed by this function and become part of the constructed op tree.
+I<defsv_off> is the pad offset of the scalar lexical variable that will
+be affected.
+
+=cut
+*/
+
 OP *
 Perl_newGIVENOP(pTHX_ OP *cond, OP *block, PADOFFSET defsv_off)
 {
@@ -5393,7 +5706,19 @@ Perl_newGIVENOP(pTHX_ OP *cond, OP *block, PADOFFSET defsv_off)
        defsv_off);
 }
 
-/* If cond is null, this is a default {} block */
+/*
+=for apidoc Am|OP *|newWHENOP|OP *cond|OP *block
+
+Constructs, checks, and returns an op tree expressing a C<when> block.
+I<cond> supplies the test expression, and I<block> supplies the block
+that will be executed if the test evaluates to true; they are consumed
+by this function and become part of the constructed op tree.  I<cond>
+will be interpreted DWIMically, often as a comparison against C<$_>,
+and may be null to generate a C<default> block.
+
+=cut
+*/
+
 OP *
 Perl_newWHENOP(pTHX_ OP *cond, OP *block)
 {
@@ -5417,6 +5742,8 @@ Perl_newWHENOP(pTHX_ OP *cond, OP *block)
 }
 
 /*
+=head1 Embedding Functions
+
 =for apidoc cv_undef
 
 Clear out all the active components of a CV. This can happen either