Improve API documentation

[sebnitu]

Problem

The API documentation in README.md is currently all in tables. This leaves no room for real code examples, parameter descriptions or anything else.

Possible Solution

Could possibly take inspiration from jest-puppeteer and format it this way:

Example: https://github.com/smooth-code/jest-puppeteer#api

[sebnitu]

This was finished in #320

Core table documentation has been removed since there have been many more modules added and they should all use the same API documentation formatting. A separate issue should be created for core documentation.