MDL-18375 calendar: renamed the userdate/usergetdate function in the calendar type to be more descriptive

I also tidied up the PHPDocs for these functions.