Added test and synopsis

Added a complete synopsis to the function to explain how it can be used.
as well as creating another test to verify using all optional parameters
to the function.