in reply to Docs notation
The notation is (loosely) Backus-Naur Form, or BNF. Many CPAN modules appear to support the default argument form of undef, but unfortunately not all authors understand the distinction between the examples you gave.
Some support a kind-of named parameter, which is just a hack into a hash.
update: On second thoughts, it is probably more likely to be Extended Backus-Naur Form (EBNF).