Gabriel's pull request

fix eventual issues, improve documentation and examples