Update doc comments to provide example set

Just a quick comment only edit, 

Adding examples for the use of options, and making options lists consistent (and remove confusing symbol notation)

No test coverage necessary, as this is a non-code change.