updating the source documentation and
also the README with more explanation and
examples.