Fix various issues in api reference and readme

Please see comments in individual commits for details.