fixes some comments
tweak the doc mapper interface and README wording