make shorthand parsing more robust, add unit tests and documentation