Most code I write has an API with a rather simplistic look, which covers the inner working of the code. I keep the API functions simple code-wise, too, if I can, so that a person can read them and get a good idea of what's going on.

As far as error handling, always use Carp -- it lets the user know where in HIS code the error started, and can even give a stack backtrace to show what propagated the error. Also, consider having function return false and setting some package error variable.

japhy -- Perl and Regex Hacker