update examples in readme
change formatting of api doc sections