added doc and addressed most recent comments