I don't know enough to give any examples, but from what I've read in other threads, it might be a good idea to develop a test suite that the present code passes. If your updated code still passes, you can have some assurance that you haven't bollixed things up too badly. :-)
You can use Class::Contract and Params::Validate to create a syntax of "how stuff should work," from which you can write a lexer to create documentation for. Hardish work, but very rewarding when it works.