add some minor notes on semantics, closes #18