some more API documentation (and trying out Github flavored markdown)