how else would you know what your API consists of?(it shouldn't be magic)

I agree, and that is what POD is for. Remember that a lot of programs/modules have POD at the very end of the code (I've seen my fair share from the CPAN). As a programmer who wishes to learn the API I can do a quick perldoc foo and (hopefully) get everthing I need. I was referring to code where every method is documented by the type of comments I showed in my root node, including those private or debug methods of a class which won't be in the POD.

-- vek --