added some documentation to the function header
fixed small issue that could occur with wrong evaluated parameters
added example on pattern tokens usage