latest changes to dapi, plus updates to inline code comments themselves