DOC: notes on implementation