Perl 5 guts are inconsistent and perl's ref counting is somewhat sub optimal, this is part of the desire for a total overhaul. If you wanted to submit updates to the documentation you would send them as patches to p5p. Here are the patching guidelines Perlguts.pod is a real doc in the pod/ dir. Perlapi.pod is autogenerated by embed.pl. NB: embed.pl also autogenerates perlapi.c Read the header of perlapi.c to find the correct files to edit that eventually become perlapi.pod.