Move crate documentation to README and add code example

[wiktor-k]

The old root module documentation referred to the unused "new" module. This PR cleans up the docs a bit and adds code example which gets executed as part of the unit tests.