timeslice needs better unittests and improved documentation.

[ahnitz]

There's been a number of issues that are thought to be related to some indexing bugs in the time slice method. There are two things that would be useful to improve. (1) better unittests that cover some of the failure modes to prevent future regression. (2) some better documentation so the expected behavior is more.

#4655 may have fixed the most serious issue which was caused by a mistake in the indexing logic. This may be the cause of issues like #4643.

We should make sure that any unittest may be able to catch such cases.