fix README links to work with YARD
add other example API descriptor
fix related link
Merge pull request #204 from mdsol/feature/fix_doc_links

Merged!