add typehints to date classes
polished the docblocks in the date classes a bit
closes #914
ported [3690/branches/0.11], refs #914