For example, if you were to take what BrowserUK is saying seriously, you would insist that perlguts should not exist.

Au contraire!

perlguts is a great example, but for exactly the opposite reasons to those you seem to think. It doesn't describe an implementation; the names of varibles used for loop counters; or the algorithm used (for example) to calculate the hash of a key for an associative array.

It is user documentation describing an API.

In this case, the users aren't Perl programmers, they are XS programmers. It is, in part, derived from embeded, interleaved tags (in the manner of JavaDoc or Doxegen). But not from embedded prose re-describing the internal implementation. XS is an abstract API, implemented through C macros, and perlguts documents that API at that level of abstraction.

And to reinforce the power of that abstraction, when Dave Mitchell re-implemented large chunks of the underlying code for 5.10.0, (actually 5.9.something). to reduce the memory footprint of many of the internal structures; Perlguts hardly changed at all. Your own example makes my points above more strongly than I ever have.

There's nothing "religious", no "neat, idealized doctrines" involved. Just simple, practical, proven methodology derived from hard won experience. Not my ideas, nor my experience, but that of 50 years of those that went before us.