transitions: doc and minor code improvements (#18)