Perl_doref(): improve code comments

Having just messed with this function, I understand it better, so can
comment it better.

Author: iabyn

op.c

@@ -3731,16 +3731,25 @@ S_refkids(pTHX_ OP *o, I32 type)
 }
 
 
-/* Apply reference (autovivification) context to the subtree at o.
- * For example in
- *     push @{expression}, ....;
- * o will be the head of 'expression' and type will be OP_RV2AV.
- * It marks the op o (or a suitable child) as autovivifying, e.g. by
- * setting  OPf_MOD.
- * For OP_RV2AV/OP_PADAV and OP_RV2HV/OP_PADHV sets OPf_REF too if
- * set_op_ref is true.
+/* doref(): apply reference autovivification context (and scalar and
+ * lvalue context) to a subtree. For example, in:
+ *
+ *     @{expression} = ...;
+ *
+ * the expression is expected to return an AV ref. If the expression
+ * is (for example) $h{foo}, then the OP_HELEM op associated with the
+ * expression needs to be flagged with:
+ *    - OPf_MOD to indicate that it should autovivify if the element
+ *      doesn't exist
+ *    - OPpDEREF_AV to indicate that the autovivified return value should
+ *      be [] rather than undef.
+ *
+ * The 'o' parameter is the head of the expression and 'type' is the
+ * context to apply (OP_RV2AV in the example above).
+ *
+ * If 'set_op_ref' is true, it also sets the OPf_REF flag on OP_RV2[AH]V
+ * and OP_PAD[AH]V ops
  *
- * Also calls scalar(o).
  */
 
 OP *
@@ -3753,11 +3762,16 @@ Perl_doref(pTHX_ OP *o, I32 type, bool set_op_ref)
     if (PL_parser && PL_parser->error_count)
         return o;
 
+    /* iterate down the tree */
+
     while (1) {
         switch (o->op_type) {
         case OP_ENTERSUB:
             if ((type == OP_EXISTS || type == OP_DEFINED) &&
-                !(o->op_flags & OPf_STACKED)) {
+                !(o->op_flags & OPf_STACKED))
+            {
+                /* 'defined &foo' etc: downgrade from a func call
+                 * to just a special CV retrieval */
                 OpTYPE_set(o, OP_RV2CV);             /* entersub => rv2cv */
                 assert(cUNOPo->op_first->op_type == OP_NULL);
                 /* disable pushmark */
@@ -3796,6 +3810,7 @@ Perl_doref(pTHX_ OP *o, I32 type, bool set_op_ref)
                 o->op_flags |= OPf_MOD;
             }
             if (o->op_flags & OPf_KIDS && o->op_type != OP_ENTERSUB) {
+                /* propagate the context of *this* op to its children */
                 type = o->op_type;
                 o = cUNOPo->op_first;
                 continue;