[perl #37540] [TODO] core - document 'new_pad' op

[via RT]

# New Ticket Created by  jerry gay 
# Please include the string:  [perl #37540]
# in the subject line of all future correspondence about this issue. 
# <URL: https://rt.perl.org/rt3/Ticket/Display.html?id=37540 >


there have been questions lately about the use of the 'new_pad' op.
will coleda provided a failing example, which i've included below.
upon investigating, i found no tests for new_pad. furthermore, i found
no documentation for new_pad in order to start writing tests. so,
before tests can be written, the documentation needs to be found or
written.

here's the failing code snippet:
.sub _main :main

new_pad 0
$P0 = compreg "PIR"

$S0 = <<"END_PIR"
.sub a
$P1 = find_lex 1, '$a'
.end
END_PIR

  $P2 = $P0($S0)
  store_global "b", $P2

  $S0 = <<"END_PIR"
.sub 'c'
new_pad -1
$P0 = find_global 'b'
$P0 = $P0()
.end
END_PIR

$P1 = $P0($S0)

$S0 = <<"END_PIR"
.sub d
$P0 = find_global 'c'
$P0()
.end
END_PIR

  $P1 = $P0($S0)
  $P1()
.end

# fails with 'Pad index out of range'

~jerry