including lots of examples and documenting main function
api doc in readme